Evoke Entities - Evoke Product Help

Reserved Entities

Each Evoke App has three (3) reserved Entities that cannot be deleted and must be mapped to a database. These are the AppUser, AppUserGroup and Classification Entities. In addition there is one mandatory database file, EVLU, that is not mapped. These files/tables can be created automatically be Evoke.

For apps using a new database then these files/tables are simply created in the database with the properties listed in these pre-defined entities.
For apps using an existing database the properties/fields are to be mapped to different database tables and fields for population.

AppUser

The AppUser Entity is primarily used to hold the user records for authorised users of the App. The AppUser table/file is for the User Groups, User Name, Password and Login Information associated with users.

AppUser Entity records (data) is/are populated from one or more tables/files held in the repository (database) associated with your App. The AppUser table/file works in conjunction with the EVLU licensing table/file.

It is not necessary to map/create all of the properties of the AppUser File. In fact if you only mapped the loginname, password and culture then your users could login to your App, alternatively you can add additional properties to your AppUser entity if you wish to. An example of the standard full AppUser entity appears on the right. It is recommended that all the columns are created in a SQL database. Definitions of the AppUser Properties are:

Account - Not Mandatory - A String or AlphaNumeric field - can be used as part of the login process to your app to hold an account name that can be used in conjunction with the login name and password - Not currently used in standard Evoke App login processing.
Account Remember - Not Mandatory - A boolean field - UI only so not mapped to a field in the table/file in the repository - used by Evoke to create a "cookie" on the device that that the app is running on that will hold the Account locally so that it can be pre-populated during the login process - - Not currently used in standard Evoke App login processing.
CreatedBy - Not Mandatory - A String or AlphaNumeric field - can be used to hold details of the user that created this AppUser record.
Culture - Mandatory - The Culture property (field), in the AppUser record (entity) for each user, can also be set with the value from the Table of Language Culture Names, Codes, and ISO Values. Adding en-US into this property (field) will cause the date to be displayed in the MM/DD/YY format and the currency symbol used to be $, if you added en-GB in the Culture property then the date, in the running app, will be displayed for that user in the DD/MM/YY format and £ to be the currency symbol.

If you do not set the Culture property (leave it blank) then the users culture (date format, currency symbol, etc) will default to en-US (USA format).

When user records are created from within your app this property (field) you can use a Culture Classification to further refine the Culture - Set the property in the AppUser entity to be a Classification and then use a Culture Classification to set the Data Format and Currency options for a user beyond those available in the ISO values table.
CurrentAuthToken - Mandatory in the Entity definition but does not need to be mapped to a real field in database file - A String or AlphaNumeric field - for future use, not currently used by standard Evoke processing.
DateCreated - Not Mandatory - A date field - can be used to hold the date that the AppUser record was created.
DateLastLoggedin - Not Mandatory - A date field - developer maintained, todays date can be added to this field and the appuser record saved during the page load actions of the first page series. Field present to hold the date that the App User last logged in to the App if required.
Email - Not Mandatory - A String or AlphaNumeric field - can be used to hold the email address of the User.
FirstName - Not Mandatory - A String or AlphaNumeric field - can be used to hold the first name of the User.
LastName - Not Mandatory - A String or AlphaNumeric field - can be used to hold the last name of the User.
LoginName - Mandatory - A String or AlphaNumeric field - used as part of the login process to your app to hold the users Login name that is validated as part of the standard Evoke App login processing.
loginNameRemember - Not Mandatory - A boolean field - UI only so not mapped to a field in the table/file in the repository - if present used by Evoke to create a "cookie" on the device that that the app is running on that will hold the user's Login name locally so that it can be pre-populated during the login process as part of standard Evoke App login processing.
Password - Mandatory - A String or AlphaNumeric field - used as part of the login process to your app to hold the users Password that is validated as part of the standard Evoke App login processing. The authentication method for the password is set in the App Settings section of each App Design, by default a simple match authentication is included and used.
Password Remember - Not Mandatory - A boolean field - UI only so not mapped to a field in the table/file in the repository - if present used by Evoke to create a "cookie" on the device that that the app is running on that will hold the user's password locally so that it can be pre-populated during the login process as part of standard Evoke App login processing.
Security Profile - Not Mandatory - A boolean field - UI only so not mapped to a field in the table/file in the repository - for future use, not currently used by standard Evoke processing.
FirstDayInWeek - Not Mandatory - An AlphaNumeric field - used so that, by individual user, the calender widget can start on any day of the week. For Sunday set this field to "Sunday", "Monday" for Monday, etc. By default the start day will be Monday.
PageSeriesAfterLogin - Not Mandatory - An AlphaNumeric field - If a property named "PageSeriesAfterLogin" is created in the AppUser entity, this value will be used (if it is not blank) as a user's initial page series after successful login
OnMeteredConnection - Not Mandatory - An Boolean field - If a property named "OnMeteredConnection" is set to {true} then Templates can have a flag set on the Image Widget (called Metered Connection Check) that stops the image being downloaded to the device (for this user) to save using the users "data" allowance.
UserGroups - Mandatory in the Entity definition but does not need to be mapped to a real field in database file - A joined, linked or embedded entity field - if present used by Evoke to provide access control for security and unique navigation by user. Please refer to AppUserGroups description below.

AppUserGroup

The App User Group Entity is used to hold the User Groups used in Evoke's Access Control system. It is populated by either a UserGroup Classification or exposing the User Groups as a global datasource and can have multiple entries. If you use the Classifications method then the entries should match those set up in the Access Control setup.

User Groups - Not Mandatory - An Alphnumeric or a Classification field - if used as a Classification it contains the "User Group" classification. Please refer to the additional mapping instructions for exposing these User Groups as a global datasource.

Classifications

Classifications are static lists used to populate a field/property of a table in the UI design of your app. e.g. to provide a drop down selection of product names, standard responses to questions, etc. It is probable that you will want some of the Properties (data entry boxes) in your App UI to be populated by the App User selecting from a drop-down list of options. In Evoke these are "Classifications".

Classifications are defined in the Evoke Classifications menu option and each Classification group is populated either from:

a Classification table in your backend database
via a selection from multiple tables in your backend database or
a fixed list that you define in your database.

If you are using a separate Classifications table/file in your database to hold your classifications then you can simply use the mandatory Classifications Entity that contains the following fields and map these to a corresponding file/table and fields in your database. An example of the data in a Classifications file appears on the right:

Type - A String or AlphaNumeric field - holds the classification name you have used
Code - A String or AlphaNumeric field - holds the Classification option or value for the drop down, multiple entries equal multiple options/values in the drop down.
Description - A String or AlphaNumeric field - holds an optional description value.
Info1 - A String or AlphaNumeric field - will be used to set the drop down order - user numbers or letters to set the order e.g. a, b c, d...)
Info2 - A String or AlphaNumeric field - a free format field except for the classification culture.
Info3 - A String or AlphaNumeric field - a free format field except for the classification culture.

Culture Classification

The Culture Classification, by default, is used to set the Data Format and Currency options for a user and is defined as follows: 'code/value'= region code i.e. en-GB for UK, en-US for USA, en-AU for Australia, fr-FR for France, etc, description'=currency name, 'info2'=currency symbol and 'info3'=dateformat for this user e.g. MM/DD/YYYY, DD/MM/YYYY etc. Culture is used in the AppUser Entity. The common Culture codes (including UK, USA, Australia, etc) are included as defaults. Further cultures OR if you need to redefine a culture can be added to your Classification file as shown in the image.

User Group Classification

The User Group Classification, as seen in the image on the right, is used to set the user groups in the AppUserGroup entity. The data in the Classification file will contain as many entries as you have user groups set up in Evoke so that these can be selected and used when updating user records.

Creating the EVLU table/file

The licensing terms of Evoke require that you create a very small table/file within your database called "EVLU". This file/table is used by Evoke licensing and users of your app will not be able to log into your app if it does not exist or correct entries in the table/file do not exist. You do not need to include it in your app Entities or complete the data mappings for this table/file BUT the table/file must exist in your database and, in a SQL database, have columns named as below.

For each valid user of your app (usually these are AppUser records) then an EVLU file entry must exist and contain, in the key field, the username in lowercase. If you add AppUser records through your Evoke App then a corresponding EVLU record will be created with the correct key.

The EVLU Columns/Properties

For SQL databases, you need to create a table called EVLU with 2 columns, specifically named as below:
Column name: EVLUID data type: string (primary key)
Column name: INFO data type: string

For MultiValue databases, you need to create a file called EVLU. No dictionary items need creating however the file will have the two properties detailed above.

EVLU Usage

The EVLUID (the key or @ID field of the file) needs to the user ids (login IDs) of the users you want to be able to access your app IN LOWERCASE. This allows you to have a user file will many users in it but to only authorise selected users to acces you app.

The second field (INFO) is initially blank and is populated with the date and time that the user "Clicks Thru" the apps click thru license on their first use. This serves as your audit trail so that you have an audit (evidence, proof) that the user accepted (clicked thru) the license accepting it, with the date and time.

The EVLU record for a user will be created automatically if you create an AppUser table/file record from within the app the you design and generate using Evoke, otherwise you must create these records in your database another way.