External Entities

Last modified: February 22, 2024

1 Introduction

External entities can be added to the domain model through the Integration pane. They are displayed as purple entity containers in the domain model. External entities represent the link to the datasets that are made available through the shared data sources registered in Mendix Catalog. Data sources are collections of entity sets (that are referred to as datasets) in published OData services.

Datasets are maintained and updated in the originating app. You can consume these datasets through external entities in your app development. When the app uses the data, it retrieves it from the originating app.

External entities can be used like local entities. However, as the datasets are maintained in the originating apps, not all properties can be changed in the consuming app.

2 Adding an External Entity to an App

To add an external entity to your app model, follow these steps:

  1. In the domain model of your app, use the Integration pane to search for the entity or data source you want to use.

  2. Drag the entity into the domain model.

The entity and its attributes are then added to your app and two documents are added in the App Explorer:

  • A Consumed OData Service document that contains details of the OData service and the metadata. The logo displayed identifies the originating app of the service.
  • A Location constant that specifies the URL of the service.
 Virtual Entity and OData Service files

For more information, see Consumed OData Service.

The consumed entities of the current app are listed in the Used in your App section of the Integration pane:

 Virtual Entity and OData Service files

You can make local changes to the properties of external entities that only affect how the data is used and presented in the consuming app. All other properties are defined in the originating app and cannot be changed. When multiple external entities from the same OData service are used in a module or app, associations between the entities (made in the originating app) will automatically be made in the local module.

For more information on using published OData services and entities through the Catalog, see Consume Registered Assets.

3 Properties of External Entities

Compared to local entities, external entities have a limited number of properties that can be changed. The rest of the properties are defined in the originating app and are, therefore, read-only.

3.1 General

This group displays the general properties of the external entity. These values are defined in the originating app, so you cannot edit them. The values that you can edit will only apply to the local app:

External Entity Properties
  • Name – the name of the entity in the local app
  • From service – shows the service from which this entity originates
  • Original name – shows the name of the entity as defined in the originating app
  • Capabilities - indicates whether the service supports creating, reading, updating, and/or deleting objects
  • Create and change locally - when switched off, the app can only create and update objects when the server supports it; when switched on, the app can create and update objects, but will not be able to send them to the server
  • Persistable – indicates if this a persistable external entity, which means the originating app allows retrieving (reading) objects
  • Summary – shows the description for the entity in the originating app (shown only when there is a description)

3.2 Attributes

The attributes that have been published in the OData service for the external entity are listed here. You can choose to remove attributes that the app does not need. All changes that are made to the attributes and the attribute list are applied to the local instance of the entity. As they are consumed, the changes will not affect the metadata of the consumed service that the entity is published in or the attributes of the entity in the originating app.

The following operations can be done on the attribute list:

  • Add – add attributes that were published in the OData service for the entity and were previously removed from this entity
  • Edit – edit the selected attribute from the Edit Attribute dialog
  • Remove – remove an attribute from the list

3.2.1 Edit Attribute

The Edit Attribute dialog can be used to specify a local name and add a local description.

Edit attributes
  • General
    • Name – a local name for the attribute
    • Original Name – a read-only value that displays the original name of the attribute in the originating app ¹
    • Summary – a read-only summary that displays the description for the attribute in the originating app; local descriptions are entered in the Documentation tab
    • Type – read-only values for the Type, Length, and Max length of the attribute as defined in the originating app
    • Default value - the default value for this attribute when the app creates an object (visible only when the entity is creatable)
  • Documentation – a description for the attribute as defined in the originating app

¹ For attributes that represent a property of a complex attribute, a forward slash (/) separates the name of the attribute of the entity and the name of the property of the complex type.

3.3 Associations

This tab displays the associations the external entity has with other entities that are published in the same service, and any associations that have been made with local entities. For more information on association properties in Studio Pro, see Association Tab Properties.

If the entity contains one-way navigable associations, there is a note at the top of the dialog box.

Edit attributes

The following apply for all associations with the external entity:

  • Navigability icon – an icon indicating whether an association is one-way navigable
  • Name – name of the association as displayed in the current app
  • Type – read-only for associations between two external entities
  • Owner – read-only for associations between two external entities
  • Parent – read-only for associations between two external entities
  • Child – read-only for associations between two external entities

You can Add and Edit associations to the external entity with a local entity. However, the association cannot be made from an external entity to a local entity; the local entity must be the owner of the association.

If you use an external entity in your app that is associated with other external entities from the same OData service in your app, the association will automatically be added in the domain model and be listed here.

3.3.1 Association Properties

When you Edit an association that is included in two entities exposed in the same OData service, the following properties are displayed and the only local change that can be made is the local name:

Edit external associations
  • Name – local name of the association
  • Original Name – read-only name of the association given in the originating app
  • Summary – read-only description of the association from the originating app
  • Multiplicity – read-only multiplicity values from the originating app
  • Documentation – a local description for the external entity association

If the association is one-way navigable, there is a note at the top of the dialog box.

Edit external associations one-way navigable

3.4 Documentation

You can add any local information about the external entity in this tab.

4 Authentication

Using external entities in production environments requires both publishers and consumers of OData services to set the correct authentication method.

4.1 Publishers: Setting Authentication Method

Publishers of an OData service set the type of authentication needed for it to be consumed. The following authentication methods are available:

For details on the types of authentication methods and how to set them up, see the Security section of Published OData Services.

4.2 Consuming External Entities with Authentication

When an external entity is used in an app module through the Integration pane, a consumed OData service document is added specifying the details of the consumed service. This is the API to the publishing app and the data associated with the entity.

If the service you are consuming requires authentication, you will need to add authentication credentials. Consumers of an OData service in an external entity can contact the owner of the data source to check the required authentication method and credentials.

Learn more about adding authentication information to a consumed OData service:

5 External Entity Limitations

External entities are the endpoints that are defined in the published OData service from the originating app. The consumed OData service document displays the values from the service metadata when the external entity is used through the Integration pane. The datasets associated with the entities are maintained in the originating apps.

Furthermore, external entities cannot be committed. Use the Send External Object activity to persist changes to external entities. This means the following:

  • The Commit activity does not work. Use Send External Object instead.
  • On pages, the Save button and the Save Changes event do not work when the page contains widgets that update external entities. Call a microflow that persists the changes using Send External Object instead.

For more details on consuming services and published entities, including operations that can be performed on external entities, see Consume Registered Assets in the Data Hub Guide.