Managing Entities

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.

Generate Entities from IBM Watson® Knowledge Catalog Data Assets

You can also import a new entity by using the "Import" button on the "Entities" tab at the "Overview" page of a domain or integration namespace.

Note: To be able to use this 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"!

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 Manage Cloud Pak Services settings (currently only IBM Cloud Pak for Data is supported).

Select Catalog

Select a catalog of the IBM Watson® Knowledge Catalog from which you like to import.

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.

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.

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

Note: If the data asset you selected has not been profiled in IBM Watson® Knowledge Catalog, there will be no properties shown in the table!

After clicking on the "Import" button the new entity will be created.

Field description


Field	Description
Type	This is used to specify the type of the entity.
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
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 .
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.

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 associate properties by using the "Add" button. The constructor properties are used as input to the constructor function of the external entities. For more information on 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" button. 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 "Add" button.

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 clicking on the "Info" button 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 permanently deleted.

Parent and child 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 at the details view at the "Parents" 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 details view 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 can associate a new or existing property definition to the entity by navigating to the entity instance page and using the "Add" button within the "Associated Properties at this Level" section.

There are two options when adding the properties: either to create a new property definition and associate it to the entity by selecting "Create new property", or choose one ore 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 or Integration namespaces 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 overwrite 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 behaviour:

After associating a property you can define the 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


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.