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