Domain modelling
Introductionâ
When developing services with complex business logic, the Domain Driven Design (DDD) approach aims to support to manage upcoming use cases. The approach contains a collection of rules and guidelines in order to model large and complex systems. The modelling refers to the representation of a real-world situation in which it is possible to visualize relationships and actions between different substances. Thus, making the ideation process and, later, the implementation process less painful and more organized by avoiding errors and misunderstandings.
Domain modellingâ
The Domain Modelling Extension in Cloud Solution Workbench offers rich support for modelling business domains based on the DDD principles. It comes with various modelling capabilities in the Solution Builder UI, along with support during the implementation of the actual business logic, by providing auto-generated code artefacts.
The extension is available for the following stacks:
- Java Spring Boot Stack 2.0.0 and later
- NodeJS TypeScript Stack (only for Domain services and always enabled)
Modelling the business domains is organized in domain namespaces which group logical items together. Inside a domain namespace, there are capabilities to model entities, domain services, business errors and other items inspired by the Domain Driven Design approach. To learn more about modelling domain namespaces, please check Modelling Domains.
The implementation of the domain logic can be done comfortably after cloning the project. Depending on the modelled domain, various code artefacts are auto-generated. Using those, a smooth implementation of the domain logic, which is compliant with the modelled items, is ensured. To find out more about implementing domain services please check Java Spring Boot Implementation and NodeJS TypeScript Implementation.
In addition to the Domain Modelling Extension, it is usually common practice to also enable the Aggregate Persistence Support Extension and the Business Event Support Extension.
Domain namespacesâ
Domain namespaces are used to encapsulate the business logic into its own layer. A domain namespace uses a predefined, reserved vocabulary of terms to define concepts (entities) and their relationships among themselves for a specific use case.
Create domain namespacesâ
To create a domain namespace, use the Create capability in the domain namespace's Overview section.
A domain namespace is defined by the following master data:
- Prefix: This is the prefix of the domain namespace. 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 a prefix! Furthermore, prefixes may not begin with a digit and the first character must be lowercase. A prefix can not consist more than 6 characters (required)
- Label: This is used to give a short description of the domain namespace and its lifecycle (required)
- Description: This is a long the description of the domain namespace and its lifecycle (optional)
You can also use the Open after creation checkbox to open the domain namespace for further editing after creating.
Edit domain namespacesâ
You can edit the master data of a domain namespace by clicking the Edit namespace details button in the Namespace Details section on the domain namespace's instance page.
Delete domain namespacesâ
You can delete an error by clicking the Delete namespace button in the upper right corner of the domain namespace instance page.
You cannot delete a domain namespace when:
- an Event of the current namespace is used as an Event Trigger in an Agent in a different namespace
- an Event of the current namespace is used in a Service or Command of a different namespace
- a Property definition in a different namespace uses an Entity of the current namespace as a Range
- a Property association in a different namespace uses an Entity of the current namespace as a Range Restriction
- an Entity of the current namespace is used as a Parent in a different namespace
- an Error of the current namespace is used in a Service or Command in a different namespace
- a Service or a Command in a different namespace uses an Entity of the current namespace as Input/Output/Payload
You will be asked to confirm the action before the selected namespace is permanently deleted.
Entitiesâ
Entities are objects that are comprised of properties. The entities of a project can be defined declaratively in Solution Builder. This means that you are not bound to fixed entities during project development, but you can define them freely depending on your individual requirements. The creation and editing of entities are done in the Solution Designer.
Within a bounded context we will find aggregates.These are, again, a group, but this time smaller than the bounded context, that comprises entities that refer to the same theme. An entity refers to a specific object. It has a consistent identity and its own lifecycle. There are many types of entities, but we will focus on the basic ones that are used in Solution Builder.
These are the following:
-
Entities are simple objects that have their own identity and lifecycle. They can contain Properties or other entities, can be nested in other entities and root entities.
-
Root Entities are the entry-point to a cluster of entities. This encapsulated cluster is called Aggregate and has the following characteristics:
- only the entry point root entity can have references from other entities outside the aggregate
- an aggregate is a transactional atomic
- it can have references to other root entities outside the aggregate
- it has exactly one database collection where the whole aggregate is stored in
- all contained entities have the same dependent lifecycle
Additionally, root entities can contain properties or other entities, can have Commands and can have other root entities as parents or children.
-
External Entities are entities referring to so-called known entities that are situated in Integration Namespaces. This way, entities from external sources (be it third party APIs or other projects of the Solution Builder) can be integrated into and consequently used within your project. External Entities can contain properties or constructor properties and can have known entities.
Entity usagesâ
There are three types of entities available:
- Entity: They are simple value entities without an ID, containing properties that can be connected to a root entity as a local entity. They can also be used as input/output for commands and services as well as payload to events. This type of entity will not be persisted.
- Root entity: They are the only entry point to an encapsulated cluster of entities. A root entity has its own lifecycle (creation/life/deletion), contains a unique ID, properties and can persist in / delete from a database collection.
- External entity: They are used to mapping and interacting with another entity from an external source which was integrated and modelled in an integration namespace. Since they represent a pointer to an entity that resides in another domain/system, they don't have to contain all definitions of the original external entity, just some identifier properties that help loading the external entity from wherever it resides through the external entity's load functionality. It can also contain its own properties.
See also introduction to Domain Driven Design for further details.
Root entities and external entities are only available if Aggregate Persistence Support extension is enabled.
Create 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.
Entitiesâ
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. This field is only available for entities and root entities
- Label: This is used to name the entity (required)
- Short Label: This is used to give an even shorter label (optional)
- Tags: To tag the entity (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. Entities can only add other entities as parents and root entities only 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.
Edit entitiesâ
You can edit the master data of all entity types 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.
It is not possible to change the Local Identifier for an entity.
Delete entitiesâ
You can delete a 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.
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 entities. It is also possible to add parents after creation in the Parents section of the Details view. 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 Details view as well.
Inheritance rulesâ
Entities can only add other entities as parents (no root entities or external entities).
Associate properties to 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.
There are two options when adding the properties:
- create a new property definition and associate it to the entity by selecting Create new property
- choose one or many existing properties and associate them to the entity by selecting Associate existing property
Regarding already existing properties, a list of all (or all unused) properties that have been created in all Domain Namespaces or Integration Namespaces of the project 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 overwrite or adjust the pre-filled name of the association.
Edit property associationsâ
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 Edit capability.
Define association-specific behaviourâ
After associating a property you can define a specific behaviour 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, Selection element, GeoPoint, Timeâ
| Name | String | Name of the property association |
|---|---|---|
| Association | Selection | Marks the property as mandatory (1) or optional (0..1) |
Currency, Integer, Longâ
| 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 the master data of a property definition. In that case you would need to use the displayed capability Edit Property.
Sort associated propertiesâ
You can use the plus capability of the table to add a new or associate an existing property at a specific location. Alternatively, the options "Move to top", "Move up", "Move down" and "Move to bottom" are available in the inline capability of the row.
Remove property associationsâ
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.
Visualize modelled elementsâ
You can easily create plantUML diagrams by either inserting native plantUML syntax in a codeblock or auto-generate a
diagram by clicking on the "Insert diagram" button or using the k5 command.
For all kinds of diagrams the placeholder, ns has to be replaced with the name of the namespace that holds the object
for which the diagram should be generated.
Root entitiesâ
aggregate ns:EntityName parents children properties commands
Replace EntityName with the name of the Root entity you want to generate a diagram for.
Options:
parents: Shows direct parent entities of the root entity that should be displayed.children: Shows all direct children of the root entity that should be displayed.properties: Shows all direct associated properties of each entity displayed in the diagram.commands: Shows all associated commands for each root entity displayed in the diagram.all: Shows direct parents, children, associated properties and commands.
By using the command without any extension the default is to show the aggregate with direct parents, without children, with properties and commands.
Propertiesâ
A property is a type specific variable/field for a value or range. properties are organized into value properties and range properties.
Create propertiesâ
You can create a new property by using the Create property capability on the Properties tab of a domain namespace's Overview page.
They are defined by using the following master data:
- Local identifier: Identifier of the property. this value must be unique within the namespace and cannot be changed afterwards. Please note that only the characters A-z (without special characters), digits and the special character "_" are permitted for naming fields! Furthermore, identifiers may not begin with a digit (required)
- Type: Defines the type of the property to be created. Types could be primitive such as text, number etc. or references such as modelled Root Entities, Entities or External Entities (required)
- Label: Label of the property (optional)
- Short label: Short label of the property (optional)
- Tags: To tag the property (optional)
- Notes: Useful information regarding the property definition (optional)
If the entity you want to reference does not exist you can directly create it by using the inline Create action in the field Type.
Property typesâ
The following property types are available:
| Name | Remark |
|---|---|
| Boolean | Type definition for truth values with the "true" or "false" property |
| Currency | Type definition for monetary amounts consisting of quantity and currency code |
| Date | Type definition for dates without time specification |
| Decimal | Allows you to save a number with up to 50 decimal places |
| Geo point | Type definition of a geo point with latitude and longitude (only available for MongoDB) |
| Integer | Allows you to save a number without decimal places |
| Localized text | Localizable text, consisting of locale and name, for shorter texts up to 200 characters (without formatting) |
| Long | Type definition for a 64 bit integer |
| Reference | Range - A link to another entity. Can also be defined as an array |
| Selection element | Type definition of a property that can take only specific values. The Enumeration Elements define the available options. If no specific values are specified for a used Selection Element, a warning appears in the Problems section. In this case, the generated source code cannot be compiled. |
| Text | Text field for short, un-formatted texts |
| Text/E-mail | Text field for MAIL content |
| Text/URL | Text field for URL content |
| Time | Type definition for time without dates specification |
| Timestamp | Type definition for specifications with date and time |
To create a new property and immediately associate it to an entity, you must use the Add property capability within the entity's instance page and select the Create new property option. In order to add and associate an existing property to an entity, you must use the Add property capability within the entity's instance page and select the Add existing property option. In this case, you are able to select any property created in any namespace within the Domain and integration namespace of the project.
Import propertiesâ
You can also import properties from a csv file by using the Import properties button on the properties tab at the Overview page of a domain namespace.
Example Header for an importable csv file:
localIdentifier;type;label;shortLabel;tags;notes;decimalPlaces;selectionElements;rangeEntityIdentifier;isList
Edit propertiesâ
You can edit the master data of a property by clicking the Edit property details button in the Property Details section on the property's instance page. Alternatively, you can use the Edit capability of each table row on the Properties tab of a domain namespace's Overview page. It can also be accessed by using the capability within the Edit Property Association action.
If the Type of a property is changed, the type-specific values are deleted.
Delete propertiesâ
You can delete a property by clicking the Delete property button in the upper right corner of the property instance page. Alternatively, you can use the Delete capability of each table row on the Properties tab of a domain namespace's Overview page.
You will need to confirm the action before the selected property is permanently deleted.
When a property is used, an extended dialog appears. For control, all places where the property is used are displayed and then you are asked to confirm the deletion. When the deletion is confirmed, the selected property is permanently deleted, as well as in all places where it was used.
Servicesâ
Services are used to perform actions that require and/or manipulate entities from a variety of different namespaces.
A service is used to apply changes to multiple aggregates at the same time or to perform complex actions that may require information from multiple namespaces or entities or even other services. In addition, services can be consumed by external resources. For example, services can be connected to UI frameworks and this way a complete application can be developed.
Create servicesâ
A service can be created by using the Create service capability on the Services tab of the domain namespace's Overview page.
Services are defined using the following master data:
- Type: There is one option available and this is the Domain Service (required)
- Local Identifier: Identifier of the service. This value must be unique within the namespace. Please note that only the characters A-z (without special characters), digits and the special character "_" are permitted for naming fields! Furthermore, identifiers may not begin with a digit (required)
- Label: Label of the service (optional)
- Short Label: Short label of the service (optional)
- Tags: To tag the service (optional)
- Notes: Useful information regarding the service definition (optional)
Services cannot have the same Local Identifier as a service or an agent in the same namespace.
Edit servicesâ
Edit master dataâ
Editing the master data of a service is available, by using the Edit capability of each table row on the Services tab of a domain namespace's Overview page. The fields that can be edited are Local Identifier, Label, Short Label and Notes.
Edit service detailsâ
Service details can be edited by clicking the Edit service details button in the Service Details section on the service's instance page.The fields that can be edited are Local Identifier, Label, Short Label and Notes.
It's not possible to edit the Type of a service.
Add input entityâ
It is possible to assign an Input entity to a service by either clicking on Create new private entity or Select existing entity in the Input section of the service's instance page. To add properties to the input entity click on the Add capability and choose
- Create new property
- Associate existing property
See Domain Properties for further details on creating properties.
Add output entityâ
It is possible to assign an Output entity to a service by either clicking on Create new private entity or Select existing entity in the Output section of the service's instance page. To add properties to the input entity click on the Add capability and choose
- Create new property
- Associate existing property
See Domain Properties for further details on creating properties.
Add business eventsâ
To add a Business Event to a service that will get published each time the service is executed, click on Add event in the Business Events section of the service's instance page. There are two options when adding an Event to a service:
- Add new event
- Add existing event
Regarding already existing events, a list of all the events that have been created in a project is shown. It is also possible to search for a specific event using the Search capability. One or more events can be selected in order to be added to the service.
Add business errorsâ
To add a Business Error to a service that will get returned each time the service cannot be executed, click on Add error in the Business Errors section of the service's instance page. There are two options when adding an Error to a service:
- Add new error
- Add existing error
Regarding already existing errors, a list of all the errors that have been created in a project is shown. It is also possible to search for a specific error using the Search capability. One or more errors can be selected in order to be added to the service.
Delete servicesâ
You can delete a service by clicking the Delete service button in the upper right corner of the service instance page. Alternatively, you can use the Delete capability of each table row on the Services tab of a domain namespace's Overview page.
You will need to confirm the action before the selected service gets permanently deleted.
Visualize modelled elements in markdownâ
You can easily create plantUML diagrams by either inserting native plantUML syntax in a codeblock or auto-generate a
diagram by clicking on the "Insert diagram" button or using the k5 command.
For all kinds of diagrams the placeholder, ns has to be replaced with the name of the namespace that holds the object
for which the diagram should be generated.
Services (Domain Services and Integration Services)â
services ns:ServiceName events agents errors all
Replace ServiceName with the name of the service you want to generate a diagram for.
Options:
events: Shows all events published by that service.agents: Shows agents within the same solution that are subscribed to a published event.errors: Shows all business errors that could be thrown by that service.all: Shows all events, agents and business errors associated to that service.
By using the command without any extension the default is to show the service with its input and output.
Business errorsâ
These errors reflect business errors and not technical errors. That means, that every time a business condition is not met, a business error is thrown to inform the end user about the reason. errors can be specified for the following elements:
Create errorsâ
Errors are created by using the Create error capability on the Errors tab of a domain namespace's Overview page or when editing Commands and Services.
Errors are defined using the following master data:
- Local Identifier: This is the identifier (name) of the error. 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 errors! Furthermore, names may not begin with a digit and the first character must be uppercase. (required)
- Error Message: This is a short message that will be used to inform the user about the business condition that is not satisfied (required)
- Tags: To tag the business error (optional)
- Error Description: This is used to give a longer description of the error that occurred (optional)
Edit errorsâ
You can edit the master data of an error by clicking the Edit error details button in the Error Details section on the error's instance page. Alternatively, you can use the Edit capability of each table row on the Errors tab of a domain namespace's Overview page. The fields that can be edited are Local Identifier Error Message and Error Description.
Delete errorsâ
You can delete an error by clicking the Delete error button in the upper right corner of the error instance page. Alternatively, you can use the Delete capability of each table row on the Errors tab of a domain namespace's Overview page.
You will need to confirm the action before the selected error gets permanently deleted. You can only delete an error if it is not in use. You can check the usages of an error by using the Info capability and navigating to the Usages section.