Entity and Association: Difference between revisions

Latest revision as of 16:25, 26 September 2022

Entities and Associations are the basic building blocks of a Domain Specific Data Model (DSDM); they represent the different real-world entities and relationships present in the domain as well as those entities' and relationship's properties.

Creating an Entity

Click on the Create menu at the top left of PHENOM and select Conceptual > Entity from the drop-down. The only entry required to save a new Entity is a valid name. Once all fields are filled in, clicking the SAVE button at the top of the page will create the new Entity.

By default, the new Entity will be created in the PhenomEntities package. Once created, a few new attributes can be edited: entity attributes, associated entities, tags...

Adding/Editing Attributes

To add a new attribute to an Entity, click the create button that appears at the bottom of the attributes section to add a new row. Attributes require a valid name and type.

Any attributes added or edited on the Entity/Association page will not be saved until the save button in the upper right corner is clicked.

Adding/Editing Associated Entities

To add a new associated entity to an entity, click the create button that appears at the bottom of the associated entities section to add two new rows. Associated Entities require a valid name and type.

Any associated entities added or edited on the Entity/Association page will not be saved until the save button in the upper right corner is clicked.

Moving an Attribute

For refactoring or other purposes, the user is able to move an Attribute from its parent Entity/Association to another. To initiate, the process, the user can either click on the dedicated button at the end of the attribute row or right-click on the Attribute in the NavTree.

In the dialog that appears, the user needs to select the Entity to which to move the selected Attribute.

A common reason for moving an attribute is refactoring previous work. For example, let's say AirVehivleType.engineTemperature used to represent the engine temperature of an air vehicle. To better document the domain, an Engine entity can be created and composed in AirVehicleType, AirVehicleType.engine, then AirVehicleType.engineTemperature can be moved to its sibling AirVehivleType.engine. The attribute can later be renamed so that the final entity composition becomes AirVehicleType.engine.temperature. As this is a pretty common use case, the Attribute Move dialog has an option to compose the target Entity/Association in the current Entity/Association if it was not already done.

Deleting/Deprecating an Entity or an Attribute

To delete, an individual Attribute or an Associated Entity, drag it from its table to the trashcan in the mid-right part of the page:

The delete button in the upper right will delete the entire Entity/Association and all of its children:

To avoid breaking the current project or someone else's, an element can only be deleted under a certain set of circumstances:

Entities and associations cannot be deleted if they are referenced as a type in an attribute or associated entity.
Entities, associations, and their children cannot be deleted if:
- They were pushed to a parent
- They also exist in a parent branch.
Attributes and associated entities cannot be deleted if they are used in a view characteristic path.
When deleting an associated entity, if there's only two associated entities in the association, both will be deleted.

When making a deletion, a confirmation popup will appear. If the element is safe the delete, the user may confirm the action. If the element being deleted breaks one or more of these rules, these will be displayed to the user including the origin of the issue and the user will be able to either cancel or deprecate the element. Doing so, the element will be flagged in the project as deprecated and every time the user will try to use that element, she/he will see the warning flag and should refrain from using it.

Note: Even if an element is safe to delete, the user can choose to deprecate it instead of deleting it.

Additional Fields

The details page of an Entity/Association displays some non-editable fields.

Last Modified By

The last editor and edit date time can be viewed here is displayed in the top right corner.

Attributes → Views

If an attribute is used by a View Characteristic, an expandable list appears in the Projectors column.

Composed In

Entities/Associations that have attributes of type the currently viewed entity/association will appear in the "Composed in" section.

Associated In

Associations that have associated entities of type the currently viewed entity/association will appear in the "Associated in" section.

@@ Line 4: / Line 4: @@
 Click on the Create menu at the top left of PHENOM and select Conceptual > Entity from the drop-down. The only entry ''required'' to save a new Entity is a valid name. Once all fields are filled in, clicking the SAVE button at the top of the page will create the new Entity.
-[[File:Phenom-data model-details entity create.png|1200px|border]]
+[[File:Phenom-data model-details entity create.png|1000px|border]]
 By default, the new Entity will be created in the PhenomEntities package. Once created, a few new attributes can be edited: entity attributes, associated entities, tags...
-[[File:Phenom-data model-details entity edit.png|1200px|border]]
+[[File:Phenom-data model-details entity edit.png|1000px|border]]
 == Adding/Editing Attributes ==
-To add a new attribute to an entity, click the create button that appears at the bottom of the attributes section to add a new row.
+To add a new attribute to an Entity, click the create button that appears at the bottom of the attributes section to add a new row. Attributes require a valid name and type.
-Attributes require a valid name and type. The type dropdown can either be down-selected by typing into it, or navigated by clicking it and scrolling through its options (associations, entities, observables):
-Existing attribute name and descriptions can be edited in-line:
-Any attributes added or edited on the Entity/Association page will not be saved until the save button in the upper right corner is clicked:
+[[File:Phenom-data model-details entity create attr.png|1000px|border]]
+Any attributes added or edited on the Entity/Association page will not be saved until the save button in the upper right corner is clicked.
 == Adding/Editing Associated Entities ==
-To add a new associated entity to an entity, click the create button that appears at the bottom of the associated entities section to add two new rows.
+To add a new associated entity to an entity, click the create button that appears at the bottom of the associated entities section to add two new rows. Associated Entities require a valid name and type.
-When you click "create" in the associated entity section, you will need to add two associated entities the first time.
-Adding associated entities to an entity will convert the entity to an association (since you're associating entities to each other).
-Associated Entities require a valid name and type. The type dropdown can either be down-selected by typing into it, or navigated by clicking it and scrolling through its options (associations, entities):
-Existing associated entity names and descriptions can be edited in-line:
-Any associated entities added or edited on the Entity/Association page will not be saved until the save button in the upper right corner is clicked:
-== Making deletions ==
-Types of Deletions
-There are two places deletions can be made on the entity/association page.
+[[File:Phenom-data model-details entity create associated entity.png|1000px|border]]
-Individual attributes/associated entities can be dragged to the trashcan in the mid right part of the page:
+<br>
+{{Info| 1= When you click "Create" in the Associated Entity section for the first time, you will need to add two associated entities.<br>
+Adding Associated Entity to an Entity will convert the Entity to an Association (since you're associating entities to each other)}}
+Any associated entities added or edited on the Entity/Association page will not be saved until the save button in the upper right corner is clicked.
+== Moving an Attribute ==
+For refactoring or other purposes, the user is able to move an Attribute from its parent Entity/Association to another. To initiate, the process, the user can either click on the dedicated button at the end of the attribute row or right-click on the Attribute in the NavTree.
+[[File:Phenom-data model-details entity move attr.png|1200px|border]]
+In the dialog that appears, the user needs to select the Entity to which to move the selected Attribute.
+[[File:Phenom-data model-details entity move attr dest.png|400px|border]]
+[[File:Phenom-data model-details entity move attr confirm.png|400px|border]]
-The delete button in the upper right will delete the entire entity/association and all of its children:
+A common reason for moving an attribute is refactoring previous work. For example, let's say AirVehivleType.engineTemperature used to represent the engine temperature of an air vehicle. To better document the domain, an Engine entity can be created and composed in AirVehicleType, AirVehicleType.engine, then AirVehicleType.engineTemperature can be moved to its sibling AirVehivleType.engine. The attribute can later be renamed so that the final entity composition becomes AirVehicleType.engine.temperature. As this is a pretty common use case, the Attribute Move dialog has an option to compose the target Entity/Association in the current Entity/Association if it was not already done.
+== Deleting/Deprecating an Entity or an Attribute ==
+To delete, an individual Attribute or an Associated Entity, drag it from its table to the trashcan in the mid-right part of the page:
+[[File:Phenom-data model-details entity delete attr.png|1000px|border]]
+The delete button in the upper right will delete the entire Entity/Association and all of its children:
+[[File:Phenom-data model-details entity delete.png|1000px|border]]
-Deletion Rules
+<br>
-DSDM content is only deletable under a certain set of circumstances, since there are many cases where content is used by other parts of the project.
-Entities and associations cannot be deleted if they are referenced as a type in an attribute or associated entity.
+To avoid breaking the current project or someone else's, an element can only be deleted under a certain set of circumstances:
-Entities, associations, and their children cannot be deleted if:
+* Entities and associations cannot be deleted if they are referenced as a type in an attribute or associated entity.
-they were pushed to a parent
+* Entities, associations, and their children cannot be deleted if:
-they also exist in a parent branch.
+** They were pushed to a parent
-Attributes and associated entities cannot be deleted if they are used in a view characteristic path.
+** They also exist in a parent branch.
-When deleting an associated entity, if there's only two associated entities in the association, both will be deleted.
+* Attributes and associated entities cannot be deleted if they are used in a view characteristic path.
+* When deleting an associated entity, if there's only two associated entities in the association, both will be deleted.
+When making a deletion, a confirmation popup will appear. If the element is safe the delete, the user may confirm the action. If the element being deleted breaks one or more of these rules, these will be displayed to the user including the origin of the issue and the user will be able to either cancel or deprecate the element. Doing so, the element will be flagged in the project as deprecated and every time the user will try to use that element, she/he will see the warning flag and should refrain from using it.
-When making a deletion, a popup will appear either preventing the deletion with reasons why (following the above rules), or a confirmation that you do indeed want to make the deletion:
+<u>Note:</u> Even if an element is safe to delete, the user can choose to deprecate it instead of deleting it.
+[[File:Phenom-data model-details entity delete confirmation.png|600px|border]]
+<br>
-Deletion of an entity/association happens immediately after confirming deletion.
+{{Info| 1= Deletion of an Entity/Association happens immediately after confirming deletion.<br>
-Deletion of attributes/associated entities happens after clicking "save".
+Deletion of Attributes/Associated Entities happens after clicking "save".}}
-These deletions go into a queue to push through with a save when you're done editing.
 == Additional Fields ==
-Last Modified By
+The details page of an Entity/Association displays some non-editable fields.
-The last editor/edit date+time can be viewed here:
-Attributes → Views
-If an attribute is used by a View Characteristic, an expandable list appears in the Views column:
-Composed In
-Entities/Associations that have attributes typing the currently viewed entity/association will appear in the "composed in" section:
+=== Last Modified By===
+The last editor and edit date time can be viewed here is displayed in the top right corner.
+[[File:Phenom-data model-details entity last modified by.png|1000px|border]]
-Associated In
+=== Attributes → Views ===
-Associations that have associated entities typing the currently viewed entity/association will appear in the "associated in" section:
+If an attribute is used by a View Characteristic, an expandable list appears in the Projectors column.
+[[File:Phenom-data model-details entity projections.png|1000px|border]]
+=== Composed In ===
+Entities/Associations that have attributes of type the currently viewed entity/association will appear in the "Composed in" section.
+[[File:Phenom-data model-details entity composed in.png|1000px|border]]
+=== Associated In ===
+Associations that have associated entities of type the currently viewed entity/association will appear in the "Associated in" section.
-Tags
+[[File:Phenom-data model-details entity associated in.png|1000px|border]]
-Tags can be edited/viewed at the bottom of the page: