Evoke Data Mappings - Evoke Product Help

When the Repositories (your physical backend databases) are defined and connected to, you will need to link the Properties/Columns (fields) that have been set up in Evoke Entities (the ones that relate to properties/columns in your actual database) to the Tables/Objects/Files and Properties/columns in the database. To do this you simply fill in your Data Mappings in Evoke. If you do not know the structure of or have access to your database then you may need to ask for some help from your IT department or your DataBase Administrator (DBA) to understand the specific structure of your company's database.

In Data Mappings all of the Repositories (Repository Profiles), that you set up in your app design, are listed (see image on the left). When you select one of these, Evoke will list all the Entities that you have previously set up and that are able to be mapped in the panel on the left. If you add a new Repository (Repository Profile) to create a new database i.e. a live version of a test database or a second separate test database, then you can use the menu in the ellipsis at the end of repository line to copy all of the mappings and selections from one Repository profile to the other by using the "Import data mappings" option.

For Each Entity you need to define the "Repository Object Name" - this is the name of the file (Repository table/object) in your database. If the file exists in your database and you have completed the "Scan Repository Objects" in the Repository section, then you can select the filename from the dropdown list available. If the file does not exist yet then you can type the filename into this textbox.
Optionally for each Entity you can set the Update Conflict Control (UCC) Auto Type. Update Conflict Control refers to the process of managing situations where more than one user modifies the data associated with the same entity instance at the same time.

For SQL databases there are two further options that should be set:

Primary Key Columns - Select, from the dropdown list, the Primary Key Column of the repository table.
Is Identity (Checkbox) - identifies if the Primary key column is also an identity (auto increment) column that will be automatically incremented, by the database, when Evoke saves a new record to the database.

For all database types there is an ellipsis menu on the Header of the "Entity General Mapping Details" that offers the following additional options for each Entity that is selected in the panel on the left:

Set Object Name to Entity Name - This simply sets the name in the "Repository Object Name" box to be the same as the Entity. It is included purely for convenience and saves typing the name if it is planned to be the same and does not yet exist.
Entity Mapping Notes - Opens a free format notes area, attached to each Entity in the Data Mappings area, that allows you to add some free format notes to describe the mappings you are creating, allowing you to refer back to these notes at a later time.
Create Repository Object - (Currently SQL Databases only) - Creates a new Table in your Repository (your database) using the "Repository Object Name" . This option is part of the exporting of Entity structures to your database.

For SQL databases only there is an ellipsis menu on the Header of the "Local Data" tab that offers the following additional options for each Entity that is selected in the panel on the left:

Validate Column Names - Completes a check that the Column names you have specified in these data mappings are actually in your database (repository) table and are spelled correctly.
Create Table Columns within Repository Object - Creates the columns relating to this Entity within your Table in your Repository (database). This option is part of the exporting of Entity structures to your database.

For all database types against each Property of Local data (properties held locally in this table/file) you can define:

Column Name (SQL) or Attribute Position (MultiValue DB) - if a property is not represented in the database then its column name or attribute position can be left blank. For SQL tables if the key is defined as a property as well as the Primary Key then the property column should be set to {key}. For MultiValue files if the item ID is represented by a property then this should be set to attribute position 0.
Data Type of the property/column (field) in your Repository (database) - this should relate to the data type that you have defined in your Entity for the Property and are shown in the dropdown list of options.
For MultiValue Databases these include: Alphanumeric, Integer, Boolean, Currency, Decimal, Date, Time
For SQL Databases these include: String, Integer, Boolean, Currency, Decimal, Data, Time, DateTime
Data Conversion - some properties e.g. decimals and currency benefit from having a conversion option to set the number of decimal places in the value i.e. to two places, etc. Boolean values can also be converted to have a value of 1 or "Y" or other as the true or false value. There is a "Build" button that will guide you through the properties that can be converted and what the conversion options are.

Against each Property of Related data (properties holding a key or link to a record or multiple records in another table/file) you need to define different options for SQL databases and MultiValue Databases:

SQL

Please review the information about SQL databases for full details of using Related Data with SQL Databases.

Direct Join - Used to create a 1 to many or 1 to 1 relationship between records in different tables. An example of a Direct Join is shown on the right, click on the image to make it bigger.
The entries are to identify the column name and data type in the current table that will be matched with columns in a different table or the current table.
Custom - Used to create an Evoke code hook in the Visual Studio Repository code where custom code can be placed to effect a join between columns in multiple tables.

Link Table - Used to create a many to many relationship between records in different tables. An example of Link Table options is shown on the right, click on the image to make it bigger.
The entries are similar to a direct join except there is an interim, independent table that has the join values.

MultiValue

Please review the information about MultiValue databases for full details of using Related Data with MultiValue Databases.

Local - the key(s) to the related record(s) is held in this field. An example of "Local" Related Data options is shown on the right, click on the image to make it bigger.
LocalSV - the key(s) to the related record(s) are held in this field as a local sub-valued list.
Remote - the key(s), 'linking' to this record, is held in the related entity (requires small modification to the CRUD to select out the related items of the related entity, there is an example of this in the generated CRUD .custom files).

EMV - Embedded MultiValues - Used when the related entity (record) is represented by one or more multivalued attributes. Need to supply a comma separated list of those attributes e.g. 7,9,10,13,14 etc.
If the related entity is a series of multivalued data e.g. the lines of an address, etc. then Evoke will need to represent this as a related Entity (with properties e.g. address line1, address line2, etc.) and the multivalued data mapped as sub-attributes e.g. 9.1, 9.2, 9.3, etc
ESV - Embedded SubValues - Used when the related entity is represented by one or more subvalued multivalues. Need to supply a comma separated list of those multivalue positions. An example of Embedded SubValues options is shown on the right, click on the image to make it bigger.
Custom - Custom CRUD code will handle the retrieval of related data. Used in instances where the key may need to be manipulated further prior to retrieval of the related entities.
None - No key storage is required

Please also see the section on Related Entities for additional information and the specific guidence on AppUser/AppUserGroups associations for examples.

In the Selections tab, each of the Selections, that have been set up in Entities can be further defined to have the "Filter arguments" to be passed to the selection definition. These are used in the Evoke Generator, when the App is generated and Evoke will create the database selection as either a) for MultiValue databases in DataBASIC CRUD (Create, Read, Update, Delete) code or b) for SQL databases in the C# repository access code for you.

A description of how to set up Selections, within Evoke Data Mappings, is available at Selections and a description of using selections to populate data sources is described here.

Update Conflict Control refers to the process of managing situations where more than one user modifies the data associated with the same entity instance at the same time. Evoke offers 3 different ways to approach this:

Custom implementation
Timestamp
GUID