Create an entity

A business entity refers to a core business object about which data is collected, stored, and managed. Entities represent key elements of business operations and are fundamental to the structure and functioning of an organization’s data model. Common examples of entities include customers, products, suppliers, employees, locations, etc.

Each entity is characterized by a set of attributes, which are specific pieces of information relevant to the entity. For instance, a Customer entity might have attributes such as name, address, contact number, and email.

This page walks you through the process of creating an entity file within your workspace.

All configuration options available for an object in the Application Builder are mirrored and accessible within the Semarchy extension for VS Code. For detailed information on business entities and all properties related to this type of object, see Entities.

Create an entity file

To create an entity file, follow these steps:

  1. From the Activity Bar, access the Explorer view.

  2. Right-click on your workspace folder.

  3. From the context menu, choose New File.

  4. Enter a name for the new entity file.
    It is recommended to include both the object name and type in the file name. Make sure to include the file extension (e.g., <EntityName>.Entity.yml).

  5. Press Enter.
    The newly created entity file is added to your workspace.

For better organization, consider grouping related objects together in dedicated directories (e.g., entities, forms, workflows, etc.). You might create an entities folder specifically to house all entities included in your model.

Design the entity

Define the object and mandatory properties

After creating your entity file, proceed to define the object and its mandatory properties:

  1. Double-click on the newly created entity file in the Explorer view to open it in the editor.

  2. Add _type: and enter Entity.

    You can use the IntelliSense feature by pressing Control+Space to view a list of suggestions immediately after creating a new file.

  3. Press Control+S (or Command+S on macOS) to save your file.
    Saving at this stage allows for IntelliSense to suggest snippets if activated.

  4. Add name: and enter your entity’s name, preferably in PascalCase for consistency.

    Alternatively, you can activate IntelliSense again to generate a snippet for this object type. Selecting the Entity snippet will populate your file with the following mandatory properties:

    name:
dataEntryAllowed: false
historizeGolden: false
historizeMaster: false
model:

    Hover over each property to view its description in a tooltip.

Define attributes and optional properties

Optionally, you can define attributes for your entity as well as other properties, as required by your project specifications.

  1. Activate IntelliSense to view a comprehensive list of available properties.

    IntelliSense dynamically updates the list of suggestions as you type, prioritizing relevant options and excluding properties already defined in the file, unless multiple identical properties are allowed for a specific object.

  2. Select atomicAttributes to insert the following attribute snippet into the design file:

atomicAttributes:
  - _type: AtomicAttribute
    name:
    abstractAtomicType:
    goldenAttribute:
    i18ned:
    lovValidationScope:
    mandatory:
    mandatoryValidationLabel:
    mandatoryValidationScope:
    multiValued:
    physicalColName:
    valueSeparator:

  1. Fill in the appropriate values according to your project requirements.

  2. (Optional) Repeat this process as needed to add multiple attributes.

  3. (Optional) Using IntelliSense, include any additional properties required to complete the structure of your entity.

Review the design file

To ensure that the file you are designing is error-free, follow these best practices:

  • Double-check the file structure and properties to ensure they accurately reflect your intended data model.

    VS Code provides features to help you avoid errors in your files:

    • Syntax highlighting: enable syntax highlighting for YAML to spot syntax errors quickly.

    • Error markers: red squiggly lines appear under problematic sections. Hover over them to see detailed error messages.

  • Use the Semarchy extension’s validation features to verify the file. Any error found is listed in the Problems view of the Panel.

    Clicking on an issue in the Problems panel navigates your cursor to the corresponding location in the file where the issue was detected.