Special Attributes

This page focuses on details about the special attributes used by the ADOxx platform for storing configuration of classes or specific instance information.

Special Attribute Basics

Special attributes have specific semantics inside of the ADOxx platform. They are recognized by the platform based on their name. Some special attributes are used to configure the use and behavior of a class and thus of its instances (like their graphical representation). These will be simply called "class attributes" on this page. Others are used to store information about instances which is relevant for the platform to work (like their position in a model). These will be simply called "instance attribute" on this page.

Special attributes for configuring classes are realized through class attributes where the relevant value is specifies through the attribute's default value. Special attributes that store instance specific information the "normal" (instance) attributes are used. Not all special attributes are relevant for each kind of class. For example Attribute Profile classes don't have a graphical representation and their instances don't have a position in a model as they exist outside of models.

The attributes configuring classes can be edited by changing their default value (see Modifying an attribute and AttributeValue facet). Alternatively some of those special attributes can be edited by selecting Class attributes... in the library management settings. The values for special instance attributes are mostly handled by the ADOxx platform directly.

List of Special Attributes

This section lists and shortly describes the known special attributes. Some of the attributes already exist in the distributed libraries while others must be created first. Their more detailed descriptions are provided in their respective sub-sections.

The following list contains the special attributes for configuring classes:

• __Conversion__: Specifies possible conversions to other classes.
• Allowed objects: Declares which objects can be placed on a swimlane object during modelling.
• AttrRep: Defines the representation of attributes of a class.
• __BehaveAsAggregation__: Indicates that the class should behave like an aggregation.
• Class cardinality: Allows to specify cardinalities for a class and its relations.
• ClassAbstract: Defines a class as abstract or concrete, preventing its instantiation.
• ClassName: Stores the class's name.
• ClassVisible: Allows to designate a class to be only accessible via programmatic means.
• GraphRep: Defines the graphical representation of a class.
• HlpTxt: Allows to provide a help text or description of the class.
• Model pointer: Names a specific Inter-model reference type attribute to follow by Ctrl + double-click on an object.

The following list contains the special attributes for storing instance specific information:

• Position: Stores the position of a (modelling) class instance.
• Positions: Stores the position information of a relation class instance.

No longer used special attributes

The following lists some of the special attributes that are no longer in use, but can be found in some libraries:

• AnimRep
• AutoConnect (in "Is inside" relation)
• External tool coupling
• VisibleAttrs
• WF_Trans

Conversion

The __Conversion__ class attribute defines and controls the conversion of a modelling object from one class to another. It is specified as part of the class that can be transformed to the other class. To allow converting the other class back it is necessary to also define the __Conversion__ attribute in the other class accordingly. The functionality is accessible through the context menu Convert of an instance of the class.

When converting three things happen. First a new object of the defined class is created. Afterwards attribute values are copied into the new object as defined in the __Conversion__ attribute. In the end the old object is deleted.

The attribute should be of a text type (Short String (STRING) or Long String (LONGSTRING)) and its value must be either empty or use a specific syntax:

{ ClassConversion } .

ClassConversion : CLASS strValue { AttributeConversion } .

AttributeConversion : ATTR strValue [ from:strValue ] .

The CLASS specifies to which other class the instances can be converted, with the name of the target class being specified through the strValue. The target class must be part of the same library. One or several AttributeConversion can be used to define which attribute values should be copied as part of the conversion. Each attribute has to be provided through an ATTR command with the strValue being the name of the target attribute. The optional from parameter can be used to provide the name of the source attribute to take the value from, otherwise it is assumed to be the same name as the target attribute.

Several conversion options can be specified by using CLASS multiple times, each with their own attribute conversions.

Examples:

Allow to convert to a class "B" and include the attributes "a1" (same in both classes) and "a2" to "b2":

CLASS "B"
  ATTR "a1"
  ATTR "b2" from:"a2"

Allow the conversion to an "Intermediate Event" or "End Event" with different lists of attributes:

CLASS "Intermediate Event"
  ATTR "Name"
  ATTR "Order"
  ATTR "Description"
  ATTR "Comment"
  ATTR "Open questions"
  ATTR "Compensation"
  ATTR "Conditional"
  ATTR "Error"
  ATTR "Escalation"
  ATTR "Message"
  ATTR "Signal"
  ATTR "Timer"
  ATTR "Parallel"

CLASS "End Event"
  ATTR "Name"
  ATTR "Order"
  ATTR "Description"
  ATTR "Comment"
  ATTR "Open questions"
  ATTR "Compensation"
  ATTR "Error"
  ATTR "Escalation"
  ATTR "Message"
  ATTR "Signal"

Allowed objects

The Allowed objects class attribute can be used to declare which objects can be placed on a swimlane object during modelling. As such it is only used in the __D_swimlane__, __S_swimlane__ and their sub-classes. If the user tries to place an object that is not allowed on a swimlane, the mouse pointer changes its look and the operation can not be performed.

The attribute should be of a text type (Short String (STRING) or Long String (LONGSTRING)) and its value must be either empty or use a specific syntax:

ALLOWED from: [ all | none ] { IncludeDefinition | ExcludeDefinition } .

IncludeDefinition : INCL strValue .

ExcludeDefinition : EXCL strValue .

The initial list of permitted modelling classes is determined through the from property and modified afterwards. A from:all means that all classes are permissible, while from:none means that no classes are permissible. The initial list is then modified using INCL to include classes and EXCL to exclude classes. The classes should be specified by their name through strValue.

Examples:

Only allow instances of the modelling classes "A" and "B" in the swimlane:

ALLOW from:none
INCL "A"
INCL "B"

Allow ever type instance except for the modelling classes "Data Object" and "Message":

ALLOW from:all
EXCL "Data Object"
EXCL "Message"

AttrRep

For most kinds classes the AttrRep class attribute controls the structure of the Notebook and representation of attributes therein. Each Notebook consists of chapters which contain the attributes. In addition, a chapter's attributes may be visually arranged in groups.

For record classes the AttrRep class attribute controls the visible columns and their sequence. It is also possible to specify a custom Notebook for model types.

The attribute should be of a text type (Short String (STRING) or Long String (LONGSTRING)) and its value must be either empty or use a specific syntax. When the value is empty, then the class will have no Notebook. For details on the syntax see the AttrRep language page.

Examples:

A Notebook structure with three chapters showing different attributes:

# Every Notebook definition has to start with the command "NOTEBOOK",
NOTEBOOK

# and every Notebook consist at least of one chapter. Which define the pages of the Notebook.
CHAPTER "Chapter I"
# The attributes will be shown in the Notebook in the specified order.
ATTR "Name"
ATTR "Position"
ATTR "Size"

# A second chapter, where other attributes are shown, one attribute is mandatory and some are visually grouped together.
CHAPTER "Chapter II"
ATTR "Value" mandatory
GROUP "Weather"
  ATTR "Temperature"
  ATTR "Type"
ENDGROUP
ATTR "Garden"

# A third chapter which reuses some of the other attributes.
CHAPTER "Chapter III"
ATTR "Size"
ATTR "Name"
ATTR "Type"
ATTR "Temperature"

BehaveAsAggregation

The __BehaveAsAggregation__ class attribute can be used to indicate that a modelling class should behave like an aggregation, similar to being a sub-class of __D_aggregation__ or __S_aggregation__.

The attribute should be of type Integer (INTEGER) and have a default value of either 1 (true) to behave like an aggregation or 0 (false) to not behave like an aggregation.

Note that the attribute is evaluated during initialization of a library, like when a Modelling Toolkit starts. Therefore, setting it on an instance level with different values for each modelling object is ignored.

Class cardinality

The Class cardinality class attribute defines the cardinalities for a modelling class. It can describe the allowed amounts of objects of the class as well as specific amounts of relations from and to this class to other modelling classes. If no cardinalities are defined then there are no restrictions for this class.

A validation of the class cardinality can be performed manually in the Modelling Toolkit for the active model by selecting the menu Model -> Check cardinalities. It is also possible check cardinalities as part of an AdoScript (see CHECK_CARDINALITIES ) or to configure the check to be performed on certain events (see "Default settings" library attribute).

The attribute should be of a text type (Short String (STRING) or Long String (LONGSTRING)) and its value must be either empty or use a specific syntax:

CARDINALITIES [ min-objects:intValue ] [ max-objects:intValue ]
    [ min-relations:intValue ] [ max-relations:intValue ]
    [ min-outgoing:intValue ] [ max-outgoing:intValue ]
    [ min-incoming:intValue ] [ max-incoming:intValue ]
    { RelationCardinality } .

RelationCardinality : RELATION strValue
    [ min-outgoing:intValue ] [ max-outgoing:intValue ]
    [ min-incoming:intValue ] [ max-incoming:intValue ]
    [ default-min-outgoing:intValue ] [ default-max-outgoing:intValue ]
    [ default-min-incoming:intValue ] [ default-max-incoming:intValue ]
    { ToClassCardinality | FromClassCardinality } .

ToClassCardinality : TO_CLASS strValue
    [ min-outgoing:intValue ] [ max-outgoing:intValue ] .

FromClassCardinality : FROM_CLASS strValue
    [ min-incoming:intValue ] [ max-incoming:intValue ] .

If any of the parameters is omitted, then no restriction is enforced on that part (min:0, max:infinite).

Through CARDINALITIES the general cardinalities for this class are specified:

• min-objects and max-objects define the amount of objects of this class necessary (min) / allowed (max) in a model.
• min-relations and max-relations define the necessary (min) / allowed (max) number of connectors (relations) of any type connected to an object of this class.
• min-outgoing and max-outgoing define the necessary (min) / allowed (max) number of connectors (relations) of any type outgoing from an object of this class.
• min-incoming and max-incoming define the necessary (min) / allowed (max) number of connectors (relations) of any type incoming to an object of this class.

The cardinalities can be further restricted on specific relation classes through RELATION, where the strValue specifies the name of the relation class:

• min-outgoing and max-outgoing define the necessary (min) / allowed (max) number of connectors (relations) of the specific relation class outgoing from an object of this class.
• min-incoming and max-incoming define the necessary (min) / allowed (max) number of connectors (relations) of the specific relation class incoming to an object of this class.
• default-min-outgoing and default-max-outgoing should be understood in context of TO_CLASS, as it is a default value which is applied to all target classes which are not explicitly named by a TO_CLASS. It specifies the necessary (min) / allowed (max) number of connectors (relations) outgoing to objects of the same target class.
• default-min-incoming and default-max-incoming should be understood in context of FROM_CLASS, as it is a default value which is applied to all source classes which are not explicitly named by a FROM_CLASS. It specifies the necessary (min) / allowed (max) number of connectors (relations) incoming from objects of the same source class.

The restrictions on relation classes can be even further details through the use of TO_CLASS (outgoing) and FROM_CLASS (incoming). These state the cardinalities for connectors outgoing to / incoming from a specific class (provided through the strValue of the command).

The cardinality restrictions can only be intensified and not eased. For example the maximum number of outgoing relations belonging to one relation class cannot be bigger as defined in the general cardinalities.

The cardinality check considers inheritance, meaning that sub-classes also count towards the specified min-/max-restrictions. For example if CARDINALITIES min-objects:5 is specified for a class A and class B is a sub-class of A, then instances of class B will count towards the min-objects:5 restriction. Each sub-class can have its own cardinality restrictions.

Examples:

Typical cardinalities for denoting the start of a process, requiring that exactly one object of the class exists and that it must have one outgoing "Subsequent" relation.

CARDINALITIES min-objects:1 max-objects:1
RELATION "Subsequent" max-incoming:0 min-outgoing:1 max-outgoing:1

Restrict any connectors of relation class "Links" to objects of this class.

CARDINALITIES
RELATION "Links" max-incoming:0 max-outgoing:0

Cardinalities that specify that there should be no "Links" connectors going out of objects of this class and also that no incoming "Links" connectors are allowed from objects of the classes "Note" and "Aggregation".

CARDINALITIES
RELATION "Links" max-outgoing:0
  FROM_CLASS "Note" max-incoming:0
  FROM_CLASS "Aggregation" max-incoming:0

ClassAbstract

The ClassAbstract class attribute specifies whether the class is an abstract class.

The attribute should be of type Integer (INTEGER) and have a default value of either 1 (true) to behave like an aggregation or 0 (false) to not behave like an aggregation.

ClassName

The ClassName class attribute holds the name of the class.

The attribute should be of type Short String (STRING). It is managed by the platform and can not be modified.

ClassVisible

The ClassVisible class attribute controls whether a class is "visible" to the user or not. Typical modelling classes are visible. When a class is specified to not be visible it means that:

• Its graphical representation is ignored.
• It can not be directly interacted with by a user.
• Its instances still belong to a specific model.
• It can not be assigned to a specific model type. Instead instances can be programmatically created in any model using AdoScript.

The attribute should be of type Integer (INTEGER) and have a default value of either 1 (true) to be "visible" or 0 (false) to not be "visible".

GraphRep

For GraphRep class attribute is used in modelling classes and relation classes to define their graphical representation. This is used not only to represent instances in the model, but also for smaller icons of the class like in the "Modelling bar". The value of the attribute specifies how to draw an object, similar to painting on a canvas.

The GraphRep allows to describe dynamic notations using control structures, like changing colors, visualized attribute values, adding icons and shapes or the entire visual notation. It is also possible to define some interactions with the user through the GraphRep. For example the value of an attribute can be edited by clicking on the attribute's value or executing a program call type attribute by clicking on a specific area (see HOTSPOT command).

The attribute should be of a text type (Short String (STRING) or Long String (LONGSTRING)) and its value must be either empty or use a specific syntax. When the value is empty, then the class will have no graphical representation and will be difficult to interact with. For details on the syntax see the GraphRep language page.

When editing the GraphRep attribute it is recommended to use the available dialog accessible through the Dialog icon next to the standard value. It contains a simple interface where the value can be entered at the top in the Text field and a preview generated in the View field by selecting the Paint button on the right.

Examples:

A simple rectangle with the text "Hello World" inside of it:

GRAPHREP

FILL color:"white"
RECTANGLE x:-1.5cm y:-0.93cm w:3cm h:1.86cm

TEXT "Hello World" w:c h:c

A graphical representation for a resizable object where the color of a shape depends on the value of the attribute "Weather":

GRAPHREP sizing:asymmetrical
SHADOW on

FILL color:"darkgray"
RECTANGLE x:-1.5cm y:-0.5cm w:3cm h:1cm

AVAL type:"Weather"
SET f:"gray"
IF (type = "rain") {
  SET f:"blue"
} ELSIF (type = "snow") {
  SET f:"white"
} ELSIF (type = "sun") {
  SET f:"red"
}
FILL color:(f)
POLYGON 4
    x1:-1.5cm y1:-0.5cm
    x2:-0.5cm y2:-1.5cm
    x3:0.5cm y3:-1.5cm
    x4:1.5cm y4:-0.5cm

FONT style:"bold" color:"black"
TEXT "Weather" y:-0.9cm w:c h:c

FONT
ATTR "Name" w:c:2.8cm h:c:0.8cm

HlpTxt

The HlpTxt class attribute provides a help text or description of the class. This description is available to the user in the Notebook through the Info button in the top right above the first chapter. The button is only available when this attribute has a non-empty value.

Model pointer

The Model pointer class attribute can specify a specific attribute of Inter-model reference type. In a model the reference of that attribute can then be follow by Ctrl + double-clicking on an object.

The attribute should be of type Short String (STRING) and have the name of an Inter-model reference attribute available to the class. You can use the Dialog icon next to the standard value to help with specifying a valid value.

Position

The Position instance attribute specifies the position and size of a modelling object in a model.

The attribute should be of type Short String (STRING). The value is managed by the platform, but can also be edited directly. It uses the following syntax:

NodeDefinition | SwimlaneDefinition .

NodeDefinition : NODE x:measureValue y:measureValue w:measureValue h:measureValue index:intValue .

SwimlaneDefinition : SWIMLANE x:measureValue y:measureValue w:measureValue h:measureValue index:intValue .

Either SWIMLANE or NODE is used as the keyword, depending on whether the position of a swimlane or another modelling class is used. The x and y values specify the position of the object. This is in relation to the top-left corner of the model and corresponds to the 0cm, 0cm coordinate of the GraphRep, so it is not necessarily the top-left corner of the drawn shape. The w and h values specify the width and height of the object. The index value specifies the layer on which the object is located. It is used to control drawing of overlapping objects, with higher values being drawn closer to the front ("on top of") over objects with lower values.

Positions

The Positions instance attribute specifies the bend-points and middle point of a connector in a model.

The attribute should be of type Short String (STRING). The value is managed by the platform, but can also be edited directly. It uses the following syntax:

EDGE intValue { BendPointCoordinates } index:intValue [ MiddleCoordinates ] .

BendPointCoordinates : x<intValue>:measureValue y<intValue>:measureValue .

MiddleCoordinates : MIDDLE x:measrueValue y:measureValue .

The intValue after the EDGE keyword specifies how many bend-points the connector has. For each bend-point one set of BendPointCoordinates is provided. These are identified by the intValue after the x or y and specify the position. The index value specifies the layer on which the connector is located. It is used to control drawing of overlapping connectors, with higher values being drawn closer to the front ("on top of") over connectors with lower values. When a connector also has a middle-point, then its coordinates are specified with the MIDDLE command. All x/y positions are in relation to the top-left corner of the model.

Best practices

• Create special attributes for configuring classes as class attributes where possible as their values are interpreted for the entire class and all its instances. While this can also be achieved with a "normal" (instance) attribute it will cause unnecessary clutter, storing an unnecessary value for the attribute with each instance.