The terms Related Entities and Related Data are used frequently through this user guide.

Entities can have associated records (Related Data) as part of their data structures, these are represented as properties with a data type of Entity. These are the Related Entities, records that are related by either an association or by a parent-child ownership relationship.

Users familiar with SQL Databases and users familiar with MultiValue Databases may understand Related Entities slightly differently, although they are basically the same.

In both instances, if you wish to associate two records together e.g. an Organisation has a single AppUser Record (the person that this Organisation is assigned to in the example on the screen on the right) that is either part of the record or associated with it then in Evoke the Organisation Entity will have a Property that is a Data Type of Entity and this can be defined as a Related Entity of the AppUser Entity (i.e. an AppUser Record).

If you wish to associate a group (list) of records to a parent record i.e. an Organisation has multiple Contacts (example on on the right) that are associated with it then in Evoke the Organisation Entity will have a Property that is a Data Type of Entity and this can be defined as a Related Entity of the Contact Entity (i.e. an Contact Record) but the "holds a List of Values" option will be ticked to indicate there are multiple Contact records that can be held in this list.

There is a further option of have a many to many relationship between records (Entities), in this case you simply define the Entity exactly as shown for Organisation and Contacts and redefine this in the associated Data Mappings. There is an example of this in each of Evoke app as the default entity "AppUser" has a many to many relationship between the "User Groups" property and the AppUserGroups Entity.

To further explain specifically for different databases.

MultiValue
In Evoke the equivalent of an item with MultiValued data is two Entities, a parent Entity and child Entity. The parent Entity represents the non multivalued data and the child Entity will have one instance per MultiValue position within the associated MultiValue group. Please review the information about MultiValue databases for full details of using Related Data with MultiValue Databases.

SQL
Evoke supports most SQL databases and allows users to continue to use and benefit from the Table structures and Views that they have incorporated by using a SQL Database. Please review the help page specifically for SQL Databases that explains in further detail how Joins and Link Tables, commonly used in SQL databases, are supported in Evoke and also how existing and new custom Middle Tier C# code can be used in an Evoke app/app design.

In the Data Mappings for these Entities you can see in the related data section how these Entities are mapped with a) in MultiValue: Local, Remote, Embedded MultiValues and Embedded SubValues and b) In SQL: Joins and Link Tables

When you use a selection, read key widget or any other read action in Evoke to read a record to Populate a DataSource, you must ask for the associated/child entities to be also populated if you wish to use them - this is done (as shown on the right) using the 'entity properties to load' option in the Editor specific part of the widget definition for ReadKey and similar selection and read widgets. Alternatively, if you are performing the read via an Evoke Click Action (on page load/button click/etc) then you would use the Click Action - RetrieveRelatedData

The Sales Order Processing demo app, included with each Evoke account, (which demonstrates using a MultiValue database) also gives a good example of this for you to review, in the section "review orders" (in the Evoke SOP app design this is the Orders page in the Review Orders Page Series) you can see a customer is selected (in this case from a drop down list) and its SalesOrders and SalesOrders.OrderLines are retrieved before being displayed in the respective Datagrids on the same page. The Example App, again included in each Evoke account, gives similar examples for SQL databases.

In summary, when an Entity (record) is read in an Evoke app (by a selection, a readkey action, or another way) then any associated records - the Related Entities (In MultiValue: embeded multivalues, subvalues, linked by local or remote keys and In SQL: linked records, joined records) - that need to be used in the UI need to be retrieved using either the Evoke Click Action 'RetreiveRelatedData' or the 'entity properties to load' option in the Template. Throughout the demonstration Example (SQL) and SalesOrderProcessing (MultiValue) app designs, included with each Evoke account, there are many further examples of different ways to retrieve and use data and related data using standard Evoke actions and widgets.

Please review the information about MultiValue databases for full details of populating Related Data with MultiValue Databases and about SQL Databases for the equivilent SQL details.