Create an entity

Entities are key components of logical modeling. This page explains how to create new entities.

Create a new entity

To create an entity:

  1. Right-click the Entities node and select Add Entity.
    The Create New Entity wizard opens.

  2. In the wizard, select the Auto Fill option and enter the following values:

    • Name: the internal name of the object.

      Due to a legacy constraint based on the maximum object name length in certain relational database management systems, physical data object names that are generated during model deployment are truncated to 25 characters. Designers should plan accordingly when choosing logical data object names.

    • (Optional) Label: a user-friendly label for this object. Since the Auto Fill checkbox is selected, the Label field is automatically filled in and can be modified.

    • (Optional) Plural Label: a user-friendly label for this entity when referring to several instances. The value for the plural label is automatically generated from the Label value and can be modified.

    • (Optional) Extends Entity: select an entity you want to extend in the context of Inheritance.

      • If the entity extends an existing one, the remaining options cannot be changed as they are inherited. Click Finish to close the wizard and then press Control+S (or Command+S on macOS) to save the editor.

      • Leave this field empty if this entity does not extend an existing one and proceed to the next step.

    • Physical Table Name: this name is used to name the physical table that will be created to store information about this entity. For example, if the physical table is CUSTOMER, then the golden data is stored in a GD_CUSTOMER table.

    • Entity Type: select the type for this entity (i.e., basic, ID-matched, or fuzzy-matched).

    • Historize Golden Records: select this option to keep track of the history of the golden data for this entity. For more information, see Data historization.

    • Historize Master Records: select this option to keep track of the history of the master data for this entity. This option is available for ID-matched and fuzzy-matched entities, if the Historize Golden Records is selected. For more information, see Data historization.

  3. Click Next.

  4. In the Primary Key Attribute screen, select the Auto Fill checkbox and enter the following values:

    • Name: the internal name of the primary key attribute (subject to the above-mentioned 25-character limit).

    • Label: a user-friendly label for this primary key attribute.

    • Physical Column Name: the name of the physical column that will be created to store values for this attribute.

    • For fuzzy-matching entities only, select the Golden ID Generation method:

      • Sequence: use this option to automatically generate the golden record ID as a sequential number. You can specify a startup value for the sequence in the Starts With field.

      • UUID: use this option to automatically generate the golden record ID as a universally unique identifier.

    • Select the ID Generation method (for all entities):

      • Sequence: use this option to automatically generate the ID as a sequential number. You can specify a startup value for the sequence in the Starts With field.

      • UUID: use this option to automatically generate the ID as a universally unique identifier.

      • SemQL: use this option to automatically generate the ID with a SemQL expression, using the entities' attributes.

      • Manual: use this option to manually provide the ID.

    • If the selected ID generation method is SemQL or Manual, you can then choose the Type and Length for the ID attribute. For fuzzy-matched entities, the type is automatically set to string.

      When attribute values appear as clear text in URLs, sensitive data—​such as social security numbers, bank account details, or tax identification numbers—​can be exposed in browser and server logs. To avoid this security risk and protect sensitive information from unauthorized exposure, model designers should avoid using sensitive data as record IDs. Use non-sensitive unique identifiers instead.

  5. Click Finish to close the wizard.
    The Entity editor opens.

  6. (Optional) In the Description field, enter a description for this entity. This description is intented for model designers.

  7. Define the user-facing documentation describing this entity. Use plain text or the Markdown syntax for rich text. This text appears in the documentation side navigation panel.

  8. (Optional) Select an icon for the entity. This icon is used in the applications to represent records from this entity when no other icon is specified.

  9. Select or deselect the Delete Enabled option to enable or disable record deletion for this entity.

  10. Press Control+S (or Command+S on macOS) to save the editor.

When an entity is created, it contains no attributes. Simple attributes and complex attributes can be added to the entity now.

You cannot modify the entity type or primary key directly from the entity editor. To change such key properties of the entity after creating it, you must use the Alter Entity option.
Make sure to set the icon and labels for the entity at the early stages, since artifacts based on that entity automatically used them.
For example, the entity icon is automatically used in application components—​business views, tabs, or transitions—​based on that entity, and you do not need to set an icon in these artifacts.

Alter an entity

Altering an entity allows modifying the key properties of an entity, including its type, inheritance, and primary key attribute.

To alter an entity:

  1. Select the entity node, right-click, and select Alter Entity.
    The Modify Entity wizard opens.

  2. In the wizard, modify the properties of the entity using the same process used for creating a new entity.

When altering an entity, it is strongly recommended to validate the model to make sure that the other elements of the model do not conflict with the modified entity definition. You must also re-deploy the model edition in order to make the changes active in the deployment data location.