Managing Entities

Entities are objects that are comprised of properties. The entities of a solution can be defined declaratively in the Microservices Designer. This means that you are not bound to fixed entities during solution development, but you can define them freely depending on your individual requirements. The creation and editing of entities are done in the Solution Designer. After opening the Solution, select the domain namespace and its component that you want to edit.

Creating New Entities

You can access an overview page of the existing entities by choosing Entities in the Domain namespace’s navigation area. You create a new entity using the Create capability

Select type of entity

There are three types of entities:

Type Description
Root Entity They are the only entry point to an encapsulated cluster of entities. A root entity has its own lifecycle (creation- life – deletion).
Entity They are simple entities, containing properties that can be connected to a root entity as a local entity and can be used as input/output to commands and services as well as used as payloads to events.
External Entity They are used to map and interact with another entity from an external source. which was integrated and modeled in the integration namespace.

Define root entity master data

Root entities are defined using the following master data:

Property Description
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.

This field is mandatory.

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. This field is only available for Entities and Root entities.
Label

This is used to name the entity.

This field is mandatory.

Short label

This is used to give an even shorter label.

This field is optional.

Notes

This is a long description of the entity and its lifecycle.

This field is optional.

Parents This specifies one or more entities from which the new entity is meant to inherit properties and commands. Entities can only add other entities as parents and root entities other root entities. This field is only available for Entities and Root entities.
Database collection

This is the name of the collection of resources (instances) in the database of the specific root entity.

This field is mandatory.

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

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

Define entity master data

Entities are defined using the following master data:

Property Description
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.

This field is mandatory.

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. This field is only available for Entities and Root entities.
Label

This is used to name the entity.

This field is mandatory.

Short label

This is used to give an even shorter label.

This field is optional.

Notes

This is a long description of the entity and its lifecycle.

This field is optional.

Parents This specifies one or more entities from which the new entity is meant to inherit properties and commands. Entities can only add other entities as parents and root entities other root entities. This field is only available for Entities and Root entities.

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

Define external entity master data

External entities are defined using the following master data:

Property Description
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.

This field is mandatory.

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. This field is only available for Entities and Root entities.
Label

This is used to name the entity.

This field is mandatory.

Short label

This is used to give an even shorter label.

This field is optional.

Notes

This is a long description of the entity and its lifecycle.

This field is optional.

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

Editing Entities

You edit the master data using the Information capability on the entity instance page. When editing all types of entities, you can overwrite the values for label, short label, notes and abstract (this one is only for entities and root entities). It is not possible to overwrite the type and the local identifier for all three types of entities. The overwritten values are lost as soon as the editing action has been completed.

Constructor Properties for externals as well as known entities and Documentation

An external entity has two types of properties the Associated properties and the Constructor properties. The Associated properties are those assigned to the local instance of the external entity. You can add and associated property by using the Add capability. The Constructor properties are those for which their values are used as input to the constructor function of the external entities. For more information regarding adding properties see also the chapter Managing properties.

Known entities were created in the integration namespace as Entities. You can add a known entity by using the Add capcability. A list of all entities that were created in the integration namespace will appear. You can choose one or more elements from that list. To select the entities use the capability Add.

By using the Edit documentation capability, the documentation of the specific external entity can be edited. There are three possible sections that can be filled: constructor operation, load operation and validate operation.

Deleting Entities

You can delete an entity by using the inline Delete capability in the Associate Commands at this Level section of the root entity’s overview page. Alternativerly, you can use the Information capability to access the details view and there you can use the Delete capability.

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 the Usages section.

You will need to confirm the action before the selected entity is permanately deleted.

Parent and children entities

You can assign any number of parent entities while creating an entity or root entity. It is also possible to add parents after creation by accessing the Information capability of an already created entity (or root entity) and navigating to the parent’s section. Each entity for which a parent was assigned is called a child of the parent entity. All children inherit properties and commands from their parents. You can use the Remove capability to remove the assignment of a parent to an entity within the Information capability as well.

Inheritance Rules

Entities can only add other entities as parents and root entities only other root entities:

Child / Parent Entity Root Entity Locally Managed External
Entity YES NO - -
Root Entity NO YES - -
Locally managed YES YES - -
External - - - -

For external Entities inheritance is not supported.

Associate properties to entities

You associate a property to an entity (of all types) by binding the property to the entity (of all types).

You can associate a new or existing property definition to the Entity by navigating to the Entity instance page and using the Add capability within the Associated Properties at the Level section.

There are two options when adding the properties: either to "Create a new property " and create a new property definition and associate it to the Entity at the same time, or "Associate existing property" and choose one ore many existing properties and associate it to the Entity.

Regarding already existing properties, a list of all (or all unused) properties that have been created in all Domain or Integration namespaces of the of the solution are shown. It is also possible to search for a specific property using the Search capability. One or more property definitions can be selected in order to be added to the entity.

While associating a property you can overwritte or adjust the prefilled name of the association.

Editing a Property Association

Once you associated a property definition to an entity you can edit the information of the association within the context of an entity by using the header or inline capability.

Defining association specific behavior:

After associating a property you can define the specific behavior within the context of an entity.

Text, Text/Mail, Text/URL

Name String Name of the property association.
Association Selection Marks the property as mandatory (1) or optional (0..1).
Min. length Integer Defines the minimum number of characters of a text.
Max. length Integer Defines the maximum number of characters of a text.
Default Value String The user can specify the default value of the property.

Validation Regular Expression

String To restrict a text, Email and URL content, you can set a regular expression validation pattern. This pattern is used for validation within any modifying action

Boolean, Timestamp, Date, Timestamp, Selection Element, GeoPoint

Name String Name of the property association.
Association Selection Marks the property as mandatory (1) or optional (0..1).

Currency, Integer

Name String Name of the property association.
Association Selection Marks the property as mandatory (1) or optional (0..1).
Min. value Decimal Defines the smallest valid value (minimum value) for a numeric property.
Max. value Decimal

Defines the largest valid value (maximum value) for a numeric property.

If filled it must be bigger or equal than the Min. value

Decimal

Name String Name of the property association.
Association Selection Marks the property as mandatory (1) or optional (0..1).
Min. value Decimal Defines the smallest valid value (minimum value) for a numeric property.
Max. value Decimal

Defines the largest valid value (maximum value) for a numeric property.

If filled it must be bigger or equal than the Min. value

Decimal Places Selection List

Decimal places can be defined from 0 to 6.

The information is mandatory.

References (to already existing entities)

Name String Name of the property association.
Association Selection Marks the property as mandatory (1) or optional (0..1) or as Array
Range Restriction Selection List

For a range property, it is possible to specify the range. The restriction is only possible towards a hierarchical child element of the original value.

Range restriction is available for references to Entities or Root Entities, not for External Entities.

The range restriction cannot be set initially while adding a property.

You can change all above described property specific information but NOT master data of a property definition. For that case you would need to use the displayed capability 'Edit Property'.

Remove a Property Association

You can remove the property association by using the inline or header Remove capability.

You can only remove property associations that are not inherited. To remove inherited properties, you must go to the parent entity and remove it from there.

You will need to confirm the action before multiple selected properties are removed.