Virtual entities serve as a powerful mechanism for seamlessly integrating external services into your project. They are specifically designed to work in conjunction with controller classes, facilitating the integration process. These controller classes are responsible for handling the logic and operations related to the virtual entities, including interacting with external services, fetching data, and managing CRUD operations.
To ensure proper integration of virtual entities, it is necessary to make the required modifications in the WebApi config class. This step involves registering and configuring the virtual entities and their associated controllers. By doing so, smooth communication and data exchange between the external services and your application are facilitated.
Incorporating data from external sources through virtual entities expands the range of data sources accessible within your project. This enhancement enriches the capabilities of your project and enables a more comprehensive data-driven experience, empowering your application with a broader scope of information. By leveraging virtual entities and their collaboration with controller classes, you can seamlessly integrate external services and leverage their data and functionality within your project.
In the process of external service integration, several key steps are involved:
External Service Integration: Virtual entities act as a bridge between your project and external services. This integration process entails establishing a connection with the external service, understanding its structure and capabilities, and utilising provided APIs or SDKs.
Virtual Entity Definition: Once the connection is established, you define the structure of the virtual entity. This involves specifying the fields, relationships, and relevant metadata necessary to represent the data from the external service.
Controller Class: A controller class is created to handle the logic for performing REST operations to the external service. This class acts as an intermediary between your data service and the external service, enabling data fetching, updating, and management.
Web Config Class: The Web Config class configures the Web API to handle OData requests and responses. It maps the HTTP interactions with the external service to OData, the standardised protocol for querying and manipulating data over HTTP.
Querying and Navigation: With the virtual entities integrated, you can utilise them in your navigation and screen development within the toolkit. You can query the virtual entities using OData, perform CRUD operations, and display data from the external service alongside other entities.
By integrating virtual entities into your project, you gain the ability to leverage them in your navigation and screen development processes. This means you can effectively incorporate virtual entities into your application's user interface. You can query these virtual entities using OData, perform essential CRUD operations (Create, Read, Update, Delete), and seamlessly display data from external services alongside other entities.
By effectively leveraging virtual entities, you expand the functionality and possibilities of your project, integrating external data sources and services to work with a wider range of data and providing a richer user experience.
To create a virtual entity follow these steps:
Open your project settings and navigate to the Data section.
Locate the icon, this icon allows you to add a new virtual entity to your data model.
Click the icon, an Add a virtual entity modal window will appear on your screen.
In the modal window, provide a unique name for your virtual entity in the designated Name box.
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.
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.
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.
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.
In order to expose Virtual Entities in your project, it is necessary to add an additional service root. When you create your first Virtual Entity, the system automatically generates a custom class called WebApiConfig to act as the Service Root. It is crucial to register all Virtual Entities within the WebApiConfig class.
The WebApiConfig class, together with its CustomRegister method, plays a crucial role in configuring the ASP.NET Web API to facilitate the integration of virtual entities. It provides the necessary settings and mechanisms for enabling attribute routing, constructing the EDM using the ODataConventionModelBuilder, dynamically registering the virtual entities within the EDM, and ensuring the appropriate routing of OData requests related to these entities.
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.
