Manage Entities in the Data Model: Step-by-Step Guide

Entities are the building blocks of your data model, representing the objects or concepts that you want to structure and manipulate in your application. This guide provides a step-by-step approach to creating, configuring, and managing entities within your project, ensuring data integrity and efficient data handling.

In the ComUnity Developer Toolkit, you can create entities within your data model in two ways:

• Entities – Define entities from scratch to model your application’s specific data structures. This also includes the option to create entities from an existing SQL table, allowing you to incorporate structured data directly into your model.

• Virtual Entities – Define entities that enable your data model to interact with third-party APIs, allowing queries to these services within the Toolkit as part of the data model.

This guide covers:

• Creating and managing custom Entities

• Using Virtual Entities to integrate third-party services

• Configuring WebApiConfig to expose Virtual Entities via OData

• Copying, modifying, and deleting entities efficiently

By following this guide, you will be able to define, configure, and manage both internal and external data models while maintaining a structured approach to data querying, integration, and API management.

📖 Learn More: OData in the ComUnity Developer Toolkit

The ComUnity Developer Toolkit follows the OData specification to enable structured data querying across the platform. Once an entity is created, it is automatically exposed via OData, allowing Pages to query and interact with entity data efficiently.

For further details on how OData is utilised within the Toolkit, refer to Reference Articles/OData.

Entities

Entities define the core data structures in the ComUnity Developer Toolkit. They allow you to model data within your application by creating structured representations of objects or concepts.

This section covers the process of creating entities, including defining them from scratch and using the option to create entities from an existing SQL table.

Creating custom Entities

To create a custom entity, follow these steps:

1. In your project settings in the Toolkit navigate to Data then select Diagram or List to view your Data Model.

2. Locate the icon on the Diagram or List (shown below) view. This icon allows you to add a new entity to your data model.

   

   Diagram view of the Data model

   

   List view of the Data model
3. Click icon, and an Add a new entity modal window will appear on your screen.

   

   Add new entity modal

4. In the Entity Name box, provide a descriptive name for your entity. Choose a name that represents the object or concept it represents in your application. Note that a valid entity name is unique and cannot contain special characters or spaces.

5. Finally, click on the Add an entity button to create your custom entity.

Adding Entity Fields and Configuring Field Settings

When you create a new entity in the ComUnity Developer Toolkit, it automatically inherits from a BaseEntity, which provides several default fields (attributes). These attributes include:

1. Created: Represents the timestamp when the entity was initially created. This property is set to the exact date and time when the entity was added to the system and is immutable.

2. Modified: Indicates the timestamp when the entity was last modified. This property is updated every time the entity undergoes any changes, reflecting the most recent date and time of modification. Like the Created property, the Modified property is also immutable.

3. Deleted: Marks the entity as deleted, typically by setting a flag or status to indicate its removal from the system. Similar to the previous properties, the Deleted property is immutable.

4. <EntityName>Id: An integer (int) type property that serves as the unique identifier for all records created from the entity.

The method of viewing entities fields depends on whether they are represented in an entity diagram or as a list:

1. Diagram: For entities presented in an entity diagram, the entity fields are visually represented within the diagram itself. Each entity will have its attributes displayed directly in the diagram, providing a comprehensive overview of its structure and relationships.

2. List: If the entities are presented as a list, you can expand and view their attributes by clicking the (+) icon that precedes the entity name. This will expand the entity and display its attributes in a detailed view. Conversely, to hide the properties, you can click the (-) icon.

To add properties an entity, follow these steps:

According to Microsoft’s .NET naming guidelines, public members such as properties should use Pascal casing, where each word begins with an uppercase letter. As a result, all properties in the data model have to be capitalised to ensure compatibility with C# standards and to avoid conflicts or unexpected behaviour at runtime.

For more details, see Microsoft’s .NET Naming Guidelines.

1. Right-click on an existing property in the entity structure.

2. In the context menu, choose one of the following:

   1. "Add a property above” – Inserts a new property above the selected one.

   2. “Add a property below” – Inserts a new property below the selected one.

3. The Add Property modal appears.

4. In the Name field, provide a descriptive name for your field. Note that a valid field name is unique and cannot contain special characters or spaces.

5. Click “Add property” to insert the new property in the specified position.

6. Select the newly added property to activate it. Configure its settings in the Properties Editor, including:

   Property name	Function	Value selection
   Property Type	Select the type of data to be stored in this field. See Datatypes.	Select one from the list of 14 options.
   Entity Key	Sets the primary key.	Select the checkbox if the field is the primary key.
   Maximum Length	Defines the maximum number of characters this field can accommodate.	Enter the maximum number.
   Column Name	Defines the name for this field.	Enter a name for this field as it will appear in the database.
   Column Order	To use composite keys the Entity Framework (EF) requires you to define an order for the key properties. You can do this by using the Column annotation to specify an order. If you have entities with composite foreign keys, then you must specify the same column ordering that you used for the corresponding primary key properties. For more information: Go to Entity framework annotations URL https://docs.microsoft.com/en-us/ef/ef6/modeling/code-first/data-annotations	The order value is relative (rather than index-based) so any values can be used. For example, 100 and 200 would be acceptable in place of 1 and 2.
   Database Generated	An important database features is the ability to have computed properties. If you're mapping your Code First classes to tables that contain computed columns, you don't want Entity Framework to try to update those columns. But you do want the EF to return those values from the database after you've inserted or updated data. For more information: Go to Entity framework DatabaseGenerated URL https://docs.microsoft.com/en-us/ef/ef6/modeling/code-first/data-annotations#databasegenerated	Select one of: Computed, Identity, None.
   Minimum Length	Enter a minimum number of characters this field can accommodate	Enter the minimum number.
   Indexed	You can create an index on one or more columns using the IndexAttribute. Adding the attribute to one or more properties will cause EF to create the corresponding index in the database when it creates the database..	Select the checkbox to activate the creation of an Index.
   Field Type	Select the behaviour type for this field. See Field Types.	Select the required field type from the dropdown list.
   Title	You can enter a Title name to define a custom label for the field when it is added to a form in the UI.
   Default Value	Enter a default value for this field when a new record is created.

7. Click Save to apply the changes.

Once added, the property will be available in the entity structure and can be referenced in queries or used in data models.

Creating Entities from Existing SQL Tables

Integrate your existing data seamlessly into your data model using the ComUnity Developer Toolkit. By automatically generating entity fields from your existing tables, you save time and effort. Simply migrate your database to the ComUnity platform with the assistance of the ComUnity Team, and during entity creation, these existing tables will be readily available in your Data model. Simplify the process and ensure data consistency by leveraging this automation feature.

To create an entity from existing SQL Tables, follow these steps:

1. Follow the steps outlined in Create a Custom Entity to access the Add a new entity modal window.

2. In the modal window, under Create from existing SQL Tables, you will find a greyed-out select field.

   

   Create from existing SQL table option
3. Click on Create from existing SQL Table to activate the select field.

4. Choose an option from the select field that corresponds to the existing SQL table you want to create an entity from.

5. In the Entity Name box, provide a descriptive name for your entity. Choose a name that represents the object or concept it represents in your application. Note that a valid entity name is unique and cannot contain special characters or spaces.

6. Finally, click Add an Entity to create the entity based on the selected SQL table.

By following these steps, you can effortlessly incorporate your existing SQL tables into your data model, leveraging the power of the ComUnity Developer Toolkit.

Entity Properties

To view the entity properties in a Diagram view, simply click on the entity's header section with a grey background colour. An active entity can be identified by its blue border, and none of its entity fields will be active (active entity fields have a blue background colour). This action will open a properties dialog that displays the global properties specific to the entity.

Conversely, if you are in a List view, clicking on an entity will activate it, and an active entity will have a distinctive blue background colour. Clicking on the entity in this view will also open the properties dialog, allowing you to explore and modify the entity's global settings.

For a detailed description and explanation of each entity property, please refer to the table below.

Property Name	Description
Inherits from Entity	View Managing Inheritance in the Data Model: Configuring Entity Hierarchy and Inheritance
Entity Set Name	The name of the EntitySet in OData URLs. By default the Entity Set and SQL table name are the same.
Edit Table Security	View Setting Up Role-Bases Permissions for Entities: Access Control Configuration
Custom Property Definitions	Unsupported in V4
Table Name	SQL table name
Temporal (History) Table	Choose whether to add or remove support for storing change history
Reset Custom Code	Check to replace custom code with default template
Custom Code	Logic that executes when intercepting change operations
List Title Template	Default template used for rendering titles of lists containing items of the entity set
List Detail Template	Default template used for rendering detail line of lists containing items of the entity set.
Sort Order	Default sort order when fetching entity set
Data Service Url	Override the default OData URL for the EntitySet endpoint with a custom Web API URL handling reading, inserting, updating and deleting records.
Max Age	The valid life time for data used in automatically refreshing lists.

Copy Entities

In the ComUnity Developer Toolkit, we understand the importance of efficiency and productivity when it comes to creating entities in your data model. To help streamline the entity creation process, we provide a handy feature called Copy Entities. This function allows you to quickly duplicate existing entities, saving you time and effort by leveraging pre-existing configurations.

The Copy Entities function is designed to simplify the task of creating similar entities or replicating entities with similar properties, fields, or settings. Instead of starting from scratch and manually recreating each entity, you can utilise the Copy Entities function to duplicate an existing entity as a starting point. This not only accelerates the entity creation process but also ensures consistency and reduces the chance of errors or omissions.

To utilise the Copy Entities function in the ComUnity Developer Toolkit, follow these steps:

1. Right-click on the entity you want to copy. This action will open a context menu.

2. In the context menu, select "Copy this entity." This will trigger the opening of a modal titled Copy Entity.

3. In the Copy Entity modal, specify the name for the new entity by entering it in the New entity name box. Choose a unique and descriptive name for the copied entity.

4. Finally, click the OK button to initiate the copying process. The selected entity will be duplicated, and the newly created entity will be added to your data model.

By following these steps, you can efficiently create copies of entities within the ComUnity Developer Toolkit. This functionality allows you to speed up the entity creation process and streamline your data model management.

In the ComUnity Developer Toolkit, we understand the importance of efficiency and productivity when it comes to creating entities in your data model. To help streamline the entity creation process, we provide a handy feature called Copy Entities. This function allows you to quickly duplicate existing entities, saving you time and effort by leveraging pre-existing configurations.

The Copy Entities function is designed to simplify the task of creating similar entities or replicating entities with similar properties, fields, or settings. Instead of starting from scratch and manually recreating each entity, you can utilise the Copy Entities function to duplicate an existing entity as a starting point. This not only accelerates the entity creation process but also ensures consistency and reduces the chance of errors or omissions.

To utilise the Copy Entities function in the ComUnity Developer Toolkit, follow these steps:

1. Right-click on the entity you want to copy. This action will open a context menu.

2. In the context menu, select "Copy this entity." This will trigger the opening of a modal titled Copy Entity.

3. In the Copy Entity modal, specify the name for the new entity by entering it in the New entity name box. Choose a unique and descriptive name for the copied entity.

4. Finally, click the OK button to initiate the copying process. The selected entity will be duplicated, and the newly created entity will be added to your data model.

By following these steps, you can efficiently create copies of entities within the ComUnity Developer Toolkit. This functionality allows you to speed up the entity creation process and streamline your data model management.

Delete an entity

To delete an entity, follow these steps:

1. Select the entity you want to delete by clicking on its header section with a grey background colour. An active entity can be identified by its blue border, and none of its entity fields will be active (active entity fields have a blue background colour). This action will open a properties dialog that displays the global properties specific to the entity.

2. Alternatively, if you are in a List view, simply click on the entity you wish to delete. An active entity will be distinguished by a distinctive blue background colour.

3. Once the entity is selected, you will notice a trash can icon located in the header section. Clicking on this icon will trigger a modal window titled Delete an Entity.

4. Finally, click the "Delete Entity" button to permanently remove the selected entity from your data model.

It's important to note that deleting an entity will also remove all associated fields and any data stored within them. Exercise caution when performing entity deletions and ensure that you have appropriate backups or data migration strategies in place.

Delete an entity property

To delete an entity field, follow these steps:

1. Select the entity field you wish to delete. If you are working in a Diagram view, click on the field directly. Alternatively, if you are viewing the entities in a List view, right-click on the entity field to reveal a context menu.

2. In the context menu, select the Delete this field option. This action will initiate a confirmation modal titled Delete Field Entity.

3. Review the details presented in the modal, ensuring that you have selected the correct field for deletion.

4. Finally, click the Delete Field button to permanently remove the selected entity field from your data model.

Please note that deleting an entity field will result in the loss of any data associated with that field. Therefore, exercise caution when deleting fields and ensure that you have appropriate data backup or migration strategies in place.

Virtual Entities

In the ComUnity Developer Toolkit, Virtual Entities provide a way to model external data sources within the data model, enabling seamless integration with third-party APIs.

Unlike regular Entities, which define data structures that map to SQL tables, Virtual Entities are not linked to a database. Instead, they act as an abstraction layer, allowing data from external APIs to be retrieved and processed dynamically while still supporting OData-based queries.

Virtual Entities allow applications to interact with API-driven data just like regular entities, making it easier to integrate third-party services while maintaining a consistent query experience within the Toolkit.

Why use Virtual Entities ?

Virtual Entities allow applications to model and interact with external APIs as structured entities, ensuring:

• Consistent Data Interaction – API data is accessed through OData-based queries, just like internal data models.

• No Database Mapping Required – Since Virtual Entities retrieve data dynamically, they do not map to an SQL table.

• Seamless Integration with External APIs – API responses are handled like structured entity data within the Toolkit.

• Unified Querying Mechanism – Developers can interact with API-driven data using the same syntax and tools as regular entities.

Creating Virtual Entities

To create a virtual entity follow these steps:

1. Open your project settings and navigate to the Data section.

2. Locate the icon, this icon allows you to add a new virtual entity to your data model.
3. Click the icon, an Add a virtual entity modal window will appear on your screen.

   

   Add virtual entity modal
4. In the modal window, provide a unique name for your virtual entity in the designated Name box.

5. By default, the checkboxes for Add entity class, Add controller class, and Add controller sample code will be selected. These options generate boilerplate code for the entity and controller classes that are associated with your virtual entity. This code is placed in your project's Custom Classes. If you wish to include the generated code, you can leave these checkboxes selected. This will automatically generate the code for you. However, if you prefer to define your own custom entity and controller classes, you can unselect these checkboxes. This allows you to create and specify your own custom classes in the Custom Classes section of your project, tailored to your specific requirements.

6. Finally, click OK to create the virtual entity.

After creating a virtual entity, it will be visible in the Data section, either in the Diagram or List view. In the Diagram view, you can see the newly created virtual entity displayed with a single field, which is typically the entity ID.

An active newly created virtual entity with a single field called OrderId

When you need to add additional fields to a virtual entity, the process is similar to adding fields to a regular entity. However, it's important to declare these fields within the entity class definition located in the Custom Classes section of your project.

Furthermore, when you select a virtual entity in the Diagram/List view, it will be visually highlighted with a blue border to indicate its active status. On the right-hand side of the Toolkit, the Properties Editor will appear. This editor provides convenient access to various properties of the virtual entity, including its name, entity class, and controller class.

A Properties Editor of a Order - virtual entity

To modify the entity and controller classes, you can expand the text editor by clicking on the icon. This action allows you to access and edit the underlying codebase of your virtual entity. Utilising this feature, you can declare additional fields within your virtual class. Additionally, you can modify the controller class directly in the Data settings, eliminating the need to navigate to the Custom Classes section.

By utilising the text editor and modifying the controller class in the Data settings, you can conveniently make changes to your virtual entity, including adding fields and adjusting the behaviour of the controller, streamlining the customisation process.

The properties you define at this stage will be added to the application metadata and only these properties will be rendered in the client wherever your current virtual entity is referenced to.

Configuring WebApiConfig for Virtual Entities

After creating a Virtual Entity, it must be registered in WebApiConfig to be accessible via OData. This ensures that OData requests are correctly routed and that external services can be queried through the Web API.

To do this, navigate to Custom Classes > WebApiConfig, locate the CustomRegister method, and add an entry for the newly created Virtual Entity. Once modified, rebuild the project to apply the changes.

The WebApiConfig class ensures that:

1. Virtual Entities are registered as part of the OData model.

2. OData requests are properly routed to Virtual Entities.

3. External services can be accessed and queried through the Web API.

Modifying WebApiConfig

By default, WebApiConfig includes only system-generated entities:

using System;
using System.Web.Http;
using System.Web.Http.OData.Extensions;

namespace todo1602251024
{
	/*
	For additional details on using OData in ASP.NET Web API, visit the following link.
	https://docs.microsoft.com/en-za/aspnet/web-api/overview/odata-support-in-aspnet-web-api/
	*/
	public static partial class WebApiConfig
	{
		static partial void CustomRegister(System.Web.Http.HttpConfiguration config)
		{
			// Web API configuration and services

			// Web API routes
			config.MapHttpAttributeRoutes();

			System.Web.Http.OData.Builder.ODataConventionModelBuilder builder = new System.Web.Http.OData.Builder.ODataConventionModelBuilder();
			//builder.EntitySet<ClassName>("ClassName");

			builder.EntitySet<Custom.NotificationView>("NotificationView");
            config.Routes.MapODataServiceRoute("odata", "odata", builder.GetEdmModel());
		}
	}
}

Registering a Virtual Entity

To expose a newly created Virtual Entity (e.g., Custom.Order), update WebApiConfig as follows:

using System;
using System.Web.Http;
using System.Web.Http.OData.Extensions;

namespace blog1602251024
{
	/*
	For additional details on using OData in ASP.NET Web API, visit the following link.
	https://docs.microsoft.com/en-za/aspnet/web-api/overview/odata-support-in-aspnet-web-api/
	*/
	public static partial class WebApiConfig
	{
		static partial void CustomRegister(System.Web.Http.HttpConfiguration config)
		{
			// Web API configuration and services

			// Web API routes
			config.MapHttpAttributeRoutes();

			System.Web.Http.OData.Builder.ODataConventionModelBuilder builder = new System.Web.Http.OData.Builder.ODataConventionModelBuilder();
			//builder.EntitySet<ClassName>("ClassName");
                       builder.EntitySet<Custom.Order>("Order");

			builder.EntitySet<Custom.NotificationView>("NotificationView");
            config.Routes.MapODataServiceRoute("odata", "odata", builder.GetEdmModel());
		}
	}
}

After making these changes, rebuild the project to apply the modifications.

Key Considerations When Modifying WebApiConfig

• Explicit registration is required for each Virtual Entity.

• Ensure correct namespaces when adding entities (Custom.Todo).

• Rebuild the project after modifying WebApiConfig.

• Verify OData routes to confirm Virtual Entities are correctly exposed.