Root Entities

Root entities are special entity types, which can be defined for a business use case. They consist out of properties and can be modeled within the Solution Designer. Contrary to entities, they have their own lifecycle (creation/life/deletion), contain a unique ID and can persist in / delete from a database collection.

See also introduction to Domain Driven Design for further details.

The creation and editing of root entities are done within a domain namespace in the Solution Designer.

Create root entities

You can access an overview page of the existing entities by visiting the entities tab on the domain namespace's Overview page. You can create a new entity by using the Create entity capability.

Root entities are defined using the following master data:

  • Local Identifier: This is the local identifier (name) of the entity. It is unique within a namespace. Please note that only the characters A-z (without special characters), digits and the special character "_" are permitted for naming entities! Furthermore, local identifiers may not begin with a digit and the first character must be uppercase. The local identifier cannot be changed after creation (required)
  • Abstract: This is a checkbox field. When checked, it indicates that the entity will be abstract. If the field is checked, no instances of this entity can be created by the Solution Envoy environment. The default value is unchecked.
  • Label: This is used to name the entity (required)
  • Short Label: This is used to give an even shorter label (optional)
  • Notes: This is a long description of the entity and its lifecycle (optional)
  • Parents: This specifies one or more entities from which the new entity will inherit properties and commands. Root entities can only add other root entities as parents
  • Database Collection: This is the name of the collection of resources (instances) in the database of the specific root entity (only visible and required for MongoDB support)
  • Table Name: This is the name of the table of resources (instances) in the database of the specific root entity (only visible and required for MongoDB support). Should a table name be used that contains more than 30 characters, this may cause problems with some database systems when creating the tables. In this case, we display a warning in the Problems section. Please consult with your database administrator
  • Annotations: This allows to adjust default persistence annotations for Mongo and RDBMS.

You can also use the Open after creation checkbox to open the entity for further editing after saving.

Note:

Every change on a root entity (aggregate) is done by an associated command.

Edit root entities

You can edit the master data of the root entity by clicking the Edit entity details button in the Entity Details section on the entity's instance page. Alternatively, you can use the Edit capability of each table row on the Entities tab of a domain namespace's Overview page. The fields that can be edited are Type, Label, Short Label, Notes and Abstract (only for entities and root entities).

Note:

It is not possible to change the Local Identifier.

Warning:

If the Type of an entity is changed, the type-specific values are deleted. When changing from a Root Entity to an Entity, the Commands and the Database collection are removed. In a Java (Spring Boot) project with the RDBMS support, the Table Name is deleted if a parent is added.

Delete root entities

You can delete a root entity by clicking the Delete entity button in the upper right corner of the entity instance page. Alternatively, you can use the Delete capability of each table row on the Entities tab of a domain namespace's Overview page.

Warning:

You can only delete an entity if it is not in use. You can check the usages of an entity by using the Information capability and navigating to the Usages section. You will need to confirm the action before the selected entity is permanently deleted.

Entity inheritance

You can assign any number of parent entities while creating root entities. It is also possible to add parents after creation in the Parents section of the Details view. Please see Entity Inheritance for further details.

Note:

All children inherit Commands from their parents.

Associate and remove properties to root entities

You can associate new or existing properties to the entity by navigating to the entity's instance page and using the Add button within the Associated Properties at this Level section. Please see Associate properties to entities and Remove property associationsfor further details.