Data Mappings

When the Repositories (your physical backend databases) are defined and connected to, you will need to link the Properties (fields) that have been set up in Entities (the ones that relate to properties in your actual database) to Properties in the database. To do this you simply ask your DataBase Administrator (DBA) to help with filling in your Data Mappings in Evoke.

Repository Profiles
In Data Mappings all of the Repositories (Repository Profiles), that you set up in your app design, are listed (see top of image on the right). 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 seperate test database, then you can use the menu in the elypsis 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.

Entity General Mapping Details
For Each Entity you need to define the "Repository Object Name" - this is the name of the file (Repository object). 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.
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 object (database table)

  • Is Identity (Checkbox) - identifies if the Primary key is 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 elypsis 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 convienience 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 (database). This option is part of the exporting of Entity structures to your database.



Properties
For SQL databases only there is an elypsis 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 the 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 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, Data, Time
    For SQL Databases these include: String, Integer, Boolean, Currency, Decimal, Data, Time, DataTime

  • Data Conversion - some properties e.g. decimals and currency benefit from having a conversion option to set the number of decial 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
  • 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, independant table that has the join values.

MultiValue
  • 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.

  • 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 seperated 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 seperated 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 secition on Related Entities for additional information.



Selections
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 defined. 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 (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. Evoke offers 3 different ways to approach this:
  • Custom implementation
  • This way requires you to write a small section of code in the middle tier (C#) that handles the decision as to whether an update conflict has occurred and what to do (accept, reject or merge) if it has.
  • Timestamp
  • This approach allows a column/attribute within the repository table/file to be used to hold a date/time modified timestamp that is used to automatically control update conflict.
  • GUID
  • This approach allows a column/attribute within the repository table/file to be used to hold a GUID (Globally Unique IDentifier) value that is used to automatically control update conflict.


Video Descriptions
The two videos on the right provide detailed decriptions of data mapping using either an SQL Database or a MultiValue Database and should be reviewed for a detailed explaination of how to use Evoke DataMappings.






Mapping to MultiValue Databases.

Mapping to SQL Databases.