Entities

1 Introduction

An entity usually represents a class of real-world objects, such as customers, invoices, CDs, etc. An instance of an entity is called an object.

For example, the object representing the CD ‘Exodus’ could be an instance of the entity ‘CD’.

The properties or features of an entity are described using attributes. An attribute represents a small piece of information about an entity, such as the name or birth date of a person.

For example, you have a collection of CDs like the one in the table below:

The rows in the table are CDs. The type of the two rows is CD and this is the entity name. A specific CD like How to Dismantle an Atomic Bomb from the band U2 is called an object of the entity CD. Characteristics like the title and artist are called attributes.

2 Types of Entities

The entity type defines how the data is handled and there are three types:

• Persistable entity
  • When an entity is declared persistable, a database table is created for the entity. These type of entities are colored blue in the domain model.
• Non-persistable entity
  • Non-persistable entities are stored in the runtime memory and never get committed to the database. These type of entities are colored orange in the domain model.
• External entity
  • External entities represent the link to datasets that are made available through shared data sources registered in Mendix Catalog. These type of entities are colored purple in the domain model.

The structure of Persistable and Non-persistable entities are defined within your app. This page describes how to add and update Persistable and Non-persistable entities. For more information on persistable entities, see Persistability.

The structure of an External entity is defined in the source system where the underlying data (objects) is stored. For more information on external entities and how to add them to your app, see External Entities.

3 Properties

An example of the entity properties is represented in the image below:

Entity properties consist of the following sections:

• General
• System members
• Access rules
• Documentation

3.1 General Section

3.1.1 Name

The name property defines the name of the entity. This name is used to refer to the entity in forms, microflows, queries, constraints, etc.

The name has to be unique only within the domain model of a module. You can have two entities with the same name, provided they are in the domain models of different modules.

3.1.2 Export Level

Export level allows you to define access level to this document on the consumer (customer) side when developing an add-on module or a solution.

3.1.3 Generalization

An entity can be a more specialized version of a general entity. This means that the specialized entity has all the attributes, associations, events, and other properties of the more general entity. Using the generalization property you can specify which entity is the generalization of the entity. For example, the Car entity could have Vehicle as its generalization.

In object oriented programming (OOP) the generic term for generalization and specialization is called inheritance.

When an entity that has a specialization is retrieved (for example, in a data grid or microflow), specializations of that entity are included in the result. When a specialization is retrieved, its generalizations are not included in the result. Using the previous example, if Vehicle is retrieved, the resulting set will contain objects of types Vehicle and Car. If Car is retrieved, only objects of Car are included in the result set.

One important use of this feature is to derive functionality from the System module (for example, images from the Image entity and files from the FileDocument entity).

An example of generalization is a situation where you have entities, say a Student entity and a Professor entity, which both have some generic properties. In this case, they both have a name, telephone number, and email address and can be a member of one or more courses. Both entities are generalized in the Member entity. Conversely, this means that the Member entity is specialized in the Student and Professor entities.

For more information, and a discussion on the relative merits of using generalization or associations, see Generalization vs 1-1 Associations.

3.1.4 Image

The image property can be used to associate an image with the entity. In the domain model this image is shown in the top-left corner of the entity. The image is also shown in other places where entities are mentioned, such as the entity selection pop-up window when selecting an entity for a data view.

3.1.5 Persistable

Define whether instances of this entity can be stored in the database. For more information, see Persistability.

3.2 System Members Properties

3.2.1 Store ‘createdDate’

This property defines whether the entity contains the system attribute ‘createdDate’. This is an attribute of type Date and time that stores the date and time when the object was created. The value of this attribute is automatically set by the server upon creating an object.

3.2.2 Store ‘changedDate’

This property defines whether the entity contains the system attribute ‘changedDate’. This is an attribute of type Date and time that stores the most recent date and time when the object was changed.

3.2.3 Store ‘owner’

This property defines whether the entity has the system association ‘owner’. This is an association to the system entity ‘User’ that (initially) stores a reference to the user that created the object. This association is automatically set by the server upon creating an object.

3.2.4 Store ‘changedBy’

This property defines whether the entity has the system association ‘changedBy’. This is an association to the system entity ‘User’ that stores a reference to the user that most recently changed the object.

3.3 Access Rules Section

3.3.1 Access Rules

For more information on access rules, see Access Rules.

3.4 Documentation Section

3.4.1 Documentation

This allows you to document the entity to help you or other team members use the entity within the app.

4 Entity Dialog Box

You can also edit an entity by opening the entity properties dialog box.

In addition to the properties described above, there are also tabs which allow you to edit the following:

• Attributes
• Associations
• Validation Rules
• Event Handlers
• Indexes
• Access Rules
• Documentation

See the detailed pages for each of these tabs for more information.