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 IBM Industry Solutions Workbench offers rich support for modelling business domains based on the DDD principles. It comes with various modelling capabilities in the Solution Designer 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
- Java Spring Boot Stack 1.0.0 (only for Domain services and always enabled)
- 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 Designer. 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.
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.
Generate entities from IBM Watson® Knowledge Catalog data assets
You can also import an entity by using the Import button on the entities tab at the Overview page of a domain namespace.
To be able to use this experimental feature make sure you have set up a connection to an IBM Cloud Pak for Data instance in the Admin Settings and added a valid API key at the User Settings.
1. Select service:
Select the instance of IBM Cloud Pak for Data from which you like to import entities. IBM Cloud Pak instances can be added and managed in the Admin Settings on the Cloud Pak Services tab (currently only IBM Cloud Pak for Data is supported).
2. Select catalog:
Select a catalog of the IBM Watson® Knowledge Catalog from which you like to import.
3. Select data asset:
Now select the Data Asset you like to use for generation of an entity. The table shows name, tags and rating of the assets which have been specified in the IBM Watson® Knowledge Catalog. It is only possible to select one data asset at a time.
4. Select properties:
After selecting a data asset and clicking on Next, the wizard shows all available properties of the selected data asset. There you can select one, many or all properties to be associated with the new entity. You can edit the name and choose the data type of each property and also set it as a required field or not.
But before, you have to decide what type of entity you want to create. It is also required to give the entity a name, a label and at least one associated property. After clicking on the Import button the new entity will be created.
Property names must be unique inside a namespace! In case of duplicates we recommend referencing to already existing properties by choosing them from the "Type" drop-down menu. Property names also have to start with a lowercase character and must not contain special characters nor spaces.
If the data asset you selected has not been profiled in IBM Watson® Knowledge Catalog, there will be no properties shown in the table!
Field description:
- Type: This is used to specify the type of the entity (required)
- 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)
- Label: This is used to name the entity (required)
- Short Label: This is used to give an even shorter label (optional)
- Available Properties: This is used to add properties to the entity. These properties have been specified in the IBM Watson® Knowledge Catalog and can now get adjusted in that table. Name, type, association, and origin type are shown in the table while name, type and association can also be edited in the table. Multiple properties can be selected for import but at least one has to be selected
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.
Related links to our learning center
Course Model EntitiesProperties
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.
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.
Related links to our learning center
Course Model Domain ServicesVisualize 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.