ERASPAAS - Internet of Things
ERASPAAS - Internet of Things
2.7 Display True / Display False
2.10 Auto Generate Format / New Auto Value
This document details on the fundamentals of Eraspaas platform namely entities, relations and actions, and how they can be encapsulated into a solution. These core functionalities allow customization of the Eraspaas system data structure to adapt with specific business needs.
The Eraspaas platform provides its consumer a dedicated instance of the platform service with dedicated storage space. Such an instance of platform service is called Eraspaas domain. Each domain in Eraspaas can have its own combination of solutions with their specific data structures. Such data structures are created by configuring entities and relations, further the operations that can be performed on these entities are defined by configuring actions in the particular solution.
With every entity configured in Eraspaas system a corresponding database object is created to store records of the specified type, further along with user interfaces for viewing and editing such records, generic service end points are exposed for performing standard operations on the defined entity while also respecting the security settings.
Note: details about customization of user interface and security settings are documented in "Eraspaas Site, Handlers and Reports" and "Eraspaas Security, Abstraction and Identity" documents respectively.
This document will focus on steps involved in customization of Eraspaas platform instance by developing solutions containing primary building blocks (Entities, Relations and Actions). The Eraspaas platform is itself built as a pair of solutions on top of a core service. So when a domain is registered it has two pre-deployed solutions (System and UI).
The system solution contains the primary building block entities along with additional entities like users, departments, permissions and profiles that pertain to security and are covered in the security document, while remaining: entities, relations, actions, solutions, option sets, web folders and emails are detailed in this document.
System Setup Diagram
The above diagram shows a high-level architecture of system and solution structure in eras.
The three primary system entities namely Entities, Relations and Actions define what information can be stored and what actions can be performed within a solution. Such a solution can then be exported from one Eraspaas domain and imported into another. Further a number of such solutions can be assembled into an Eraspaas domain to provide a complete set of solutions for an organization.
A solution represents a consolidated package of entities, relations and actions along with user interface and security information relevant to the package. As such solution allows grouping of components relevant to solution functionality, such that they can be deployed or removed as a single package or ported across different Eraspaas domains.
Eraspaas Layered Architecture
The above diagram shows the different layers of Eraspaas system showing multiple solutions deployed in a domain.
The Eraspaas system is implemented over the standard Model View Presenter application architecture, with flexibility of multiple views that can be web apps or native apps.
The above diagram shows different logical layers of Eraspaas system implemented as model view presenter. To know more about MVP refer: http://en.wikipedia.org/wiki/Model-view-presenter
The Eraspaas core is a light weight engine that hosts solutions in a domain and acts as a kernel of the Eraspaas system, while solution defines a set of components that work together as a unit.
Solution Composition
The above diagram shows the standard solution composition with System, Security and UI elements relevant to the solution grouped into a single package.
The primary building blocks of Eraspaas system are entities, relations and actions. These building blocks can be assembled together to create solutions. (In-fact foundation solutions System and UI are actually built from these three primary building blocks.)
The above diagram shows the correlation between the three primary building blocks. Each entity has actions associated with it; further entities can be
related to each other using relations.
Note: besides entity specific actions there can also be actions that are common to all entities.
The key building blocks of solution are its entities. An entity can be analogised to a class in programming terms or a table in database terms. Although entities do possess a strong resemblance with database tables by creating a data store for persisting records of the given entity type, but there are a few differences worth noting:-
(a) Implicit and Explicit behaviours associated with an entity: The implicit behaviours of an entity are Actions associated with the entity that
gets auto triggered when a record of the given entity is created, updated, deleted or any other action is performed on it. While explicit behaviours are
actions that can be initiated by users. Such implicit and explicit behaviours are known as "On Event" and "On Demand" Actions in Eraspaas system.
Note: there is a third kind of action known as "On Schedule" Actions that are triggered by the time dimension.
(b) UI metadata: Besides defining the metadata about the data structure for storing records of an entity, the entity also contains basic rendering information about how the entity is displayed in standard views and forms. Further, user interface information of an entity is extensible and customizable.
(c) Field validations: Besides allowing user to define constraints like uniqueness or required, Eraspaas entities provides an assortment of attribute validation options that covers almost every possible business rule.
The above screen shows entity form with it fields.
Besides the different name fields, the entity also has additional properties namely Main Site Order and Solution. The Main Site Order value defines the display order of the entity in the Main Site (the default site) solution navigation group. A zero or empty value denotes the entity as hidden (for programmatic access only) while a positive value allows it to appear in the default user interface.
Note: after creating entity, checking the re-cache option and refreshing the page will show the entity in the left navigation of the site.
The solution field of the entity defines the solution with which entity definition can be exported (or the solution that contains the entity).
Note: solution field is available with all components that can be exported as a part of the solution such components include, entity, attribute, relation, action, etc.
Although it is possible to create entities that do not belong to any solution by leaving the field blank but the value must be provided before such entity can be exported as a part of a solution from the Eraspaas domain.
Attributes are properties of an entity that define its structure, for this a set of different attributes are associated with each entity record.
The above screen shows adding attributes to an entity.
Selecting the entity in the main view and selecting "Entity Attributes" in the right pane (prop window) allows managing attributes of the selected entity.
General guideline for naming entities and attributes - in order to avoid conflicts between entity names belonging to different solutions, it is recommended to create entities with system name prefixed with the solution's system name (MySolution_MyEntity). For attributes of such entity if belonging to the same solution then there is no need to prefix solution name with attribute's name, however if an attribute is being added to an entity belonging to different solution then the attribute's system name should be prefixed with solution name.
Although names of attribute form fields are self-explanatory but there a few that requires elaboration. The following list explains such properties of attribute:-
The Attribute Type denotes the type of attribute being created, the possible types are:
1. Single Line: to store single line of text.
2. Multiple Lines: to store multiple lines of text.
3. Date Time: to store date, time or combined date-time value.
4. Two Option: (true/false) value
5. Whole Number: to store integer value.
6. Floating Number: to store float value.
7. Decimal Number: to store floating value with higher degree of precision while computing.
8. Currency: to store monetary value, with precision similar to decimal number but with added features.
9. Option Set: for selection dropdown to choose an option.
10. Lookup: for related entity's record unique identifier.
The Is Lookup Display checkbox of attribute is usually kept with Single Line attribute type and this field represents a unique text value associated with the record; hence this field is used to display the text corresponding to the record id in lookup fields. So it serves as a primary text field that differentiates a record from another record of the same entity.
Note an attribute of type lookup cannot be used as a lookup display, as a lookup type attribute contains globally unique identifier of the related record which is automatically translated to show the unique text (is lookup display) value of the related entities record in the user interface.
The Text Format field contains regular expression that will be used to validate the data if regex pattern is provided for this field.
Decimal Scale is used for Float, Decimal and Currency field it shows the number of digits to consider post the decimal position, while the Length Value contains the total length of the field; hence allowing users to define precision for values to be stored in the given field.
Used with Two Option (Boolean) field this defines if only one record in all the records of the given entity can have this value set to true for the specific attribute. So whenever a new record has this attribute value set to true. The last record which had the value true for this field will be set back to false. (For advance control see Single True Rule)
Date Time Type is used with attribute type Date Time this values defines if the value should record Date only or Time only or complete date time for the user. Note the date time stored in the system is always a UTC (or GMT) value in ISO format. Whenever a user retrieves the value he gets the equivalent transformed value for his time zone.
2.7 Display True / Display False
Used with Two Option attribute type, sometimes when displaying values of such fields in views which by default will be True/False user might want to show Yes/No or Active/Inactive etc. These fields capture the text values to be shown for the given field values.
This value can be specified for attribute with Is Unique set to true. By default setting Is Unique will make the specific column values to be unique for all records of that entity, however sometimes it might be necessary to define the attribute to be unique in combination with another column values. For example we want the Attribute Name to be unique however two different entities can have attributes with same name but the same entity cannot have two attributes with same name so the name should be unique in combination with EntityId field of Attribute. In order to achieve this Unique Rule field captures other fields that should be considered while validating a specific attribute value to be unique. This field can contain a number of pipe separated attribute names of the same entity that should be considered for uniqueness. Also the value is grouped inside a starting and a trailing pipe if not empty.
This value can be specified for attribute type Two Option that has Is Single True set to true. This allows considering the Is Single True for a specific set or condition. Example Entity E1 has a Two Option attribute Bool1 and a Lookup attribute L1. The lookup attribute referencing records of another entity, R1, R2, etc. If the business rule is of all records of E1 for a give L1 value (say R1) only one record can have Bool1 set to True. Similarly for R2 etc. then the Single True Rule field should be set to |L1|. Note this field can contain pipe separated list of attributes of same entity. Also the value is grouped inside a starting and a trailing pipe if not empty.
2.10 Auto Generate Format / New Auto Value
This value can be specified with Is Auto Generate True attribute. The Format field allows defining a format for generating the auto value. the format should contain a sequence of zeros that will be replaced with equivalent number of digit with increment in value (the new Auto Value field contains the next integer value that will be used for the next record) also the format can contain date time parts. ex. if the desired value is 2013JUN-0001 the format will be yyyyMMM-0000. Note the Auto Generate Format can also be used with DateTime and Lookup field with Server Values to contain information like Created By, Created On, Modified By or Modified On. The Auto Generate Format for such value can be @Create_$$CurrentDateTime (to set current date time to the attribute value when the record is being created) or @Update_$$CurrentUser (to set current user to the attribute value when the record is being updated), etc.
2.11 Main View Order / Prop View Order / Main Form Order
The Order integer value define the position of the attribute in System Views and Forms (a value greater than 0) enables the field to appear the specified location in the given view or form and a value null, 0 or less than 0 prevents the field from appearing in the given view or form.
Option Set entity represents a group of options these set is used to specify for entities with Attributes as Option Set (which appear as drop down in the corresponding entities form). The Option entity related to the Option Set contains Display Name as the Text and System Name as the value of the option for the given option set.
The above screen shows option sets selected in left pane then selecting a specific option in main view and selecting Option Set - Options in the right pane, to review the options associated with the given option set.
A Relation is used to define relation between two entities to allow relating records of these entities; this works with Lookup attribute type of participating entities. The relation can be of three types -
1. One to Many (in this case the To Entity representing 'Many' should have a lookup attribute that should be specified in To Attribute)
2. One to One (in this case both entities should have a Lookup attribute each specified in From and To Attributes)
3. Many to Many (in this case neither entities need to have Lookup type attribute, rather a NtoN Relation entity should be specified (an entity with no attribute), for such entity relation attributes will be automatically created by the name FromRecordId and ToRecordId, hence the NtoN relationship between records of the participating two entities is maintained in this third entity.)
For creating a relation between two entities for example My Contact entity has a lookup attribute called Current Company that stores a reference to a My
Company entity record. A One-To-Many relationship should be created from My Company to My Contact entity.
Note it is the My Contact entity that has lookup field, signifying a contact belongs to a specify company, while a company can have multiple contacts
working for it, hence a One-To-Many relationship from My Company to My Contact.
So precisely it should always be the entity at the "Many" side that should have the lookup field in case of One-To-Many relation.
The above screen shows a One-To-Many relation between Company and My Contacts, where Current Company is a lookup attribute of My Contact entity.
From Delete Type and To Delete Type specify what should happen to the related records when the corresponding record of the related entity is deleted. So it is possible to configure either of three values -
1. Delete Children: for deletion of the related records
2. Delete Association: for removing only the association (reference) from the related records
3. Delete Prevent: to prevent the delete operation if any related record exists.
The default display order of relation specifies the order in which the relation should appear in the prop window (extreme right window) selection drop down.
An Action is any operation or behavior that changes the data in the system or performs dependent actions based on events that occur in the system. There are three types of Actions -
1. On Demand (triggered by user ex. Create Record, Update Record, etc.);
2. On Event (triggered by other Action or a sub action to an On Demand Action, ex. Create Table, Update Column, etc.);
3. On Schedule (triggered on configured time).
The above screen shows the Action form.
An action can be entity specific in which case the Entity Name (the system name of the entity) must be provided or it can be made available to all entities in which case the "Is For All Entities" option should be checked.
Some of the most commonly used actions available to all entities are listed below:
Record Actors:-
1. CreateRecord - creates a record and returns the unique id (string) of the newly created record.
2. UpdateRecord - updates the record with the given record id.
3. DeleteRecord - deletes the corresponding record based on given record id.
4. RetrieveRecord - retrieves a single record by id or by system name.
5. RetrieveMultipleRecords - retrieves multiple records (as array of record) based on query.
These actions are available through buttons in the views and forms of entities.
Attachment Actors:-
1. UploadAttachment - attaches a file to the record.
2. DownloadAttachment - retrieves a file attached to record.
3. RetrieveAttachmentList - retrieves the list of files attached to record.
4. DeleteAttachment - deletes a file from the record's attachments.
5. DeleteAllAttachments - deletes all files attached to the record.
These actions are available from the right pane (prop window) when Documents option is selected.
Import Actors:-
1. ImportData - Imports records from comma separated (csv) file into the corresponding entity.
2. ImportAttachments - Imports attachments from zip file and attaches them to corresponding records.
These actions are available from entity's view more actions dialog.
Export Actors:-
1. ExportData - Exports records as comma separated (csv) file from any given entity
2. ExportAttachments - Exports attachments of records into a zip file from any given entity.
These actions are available from entity's view more actions dialog.
Note: there are also Data Actors like RetrieveStats, RetrieveViewData, RetrieveRelationInfo, RetrieveAccessInfo, etc. which are associated with all entities, however these are designed for programmatic access and are detailed in Eraspaas Programming Guide.
Some of the common entity specific actions are ImportSolution, ExportSolution, ImportSiteContent, ExportSiteContent, ReceiveEmails, ViewReport etc. which are available from corresponding entities views more actions dialog. Some of the common "On Event" actions are Table Actors like CreateTable, CreateColumn, UpdateColumn etc. which gets triggered when Entity or Attribute records are created. SendEmail when record of Email is created or updated with Email State as "Send".
Actor Path
The "Actor Path" represents the path to the Actor who would perform the action; for Systems actions it starts with system:// while external actions it start with http:// or https:// these actions will be triggered as Http Post operation. An Action can be configured for all entities or specific entity.
Transform Format and Transform Definition
By default the Record object that is passed while triggering the action is serialized and passed to the external action; however it is possible to change the structure of the input, by providing custom xml or json string or plain text with placeholders that will be replaced with the corresponding input record field values. For example for an action a record object is passed with two fields having keys "SystemName" and "DisplayName" and corresponding values in the value of the field. And this information is to be passed to an external action in custom xml format which is understood by the external action such as:
<Input>
<SystemName>(@SystemName)</SystemName>
<DisplayName>(@DisplayName)</DisplayName>
</Input>
Then this value must be provided to the Transform Definition field. Similarly if using json format, then the Transform Definition value can be -
{"SystemName": "(@SystemName)", "DisplayName": "(@DisplayName)"}
The format of the place holder is (@FieldKey) including the brackets. Apart from the fields that are passed through the input record, it is also possible to pass server context values by specifying placeholders in the format ($$ServerValueKey) for example: ($$CurrentUser), ($$CurrentDepartment), ($$CurrentDateTime), ($$CurrentDate), ($$CurrentDomain).
Note: It is also possible to have such placeholders in the actor path, for instance like passing values in query string to external action.
More details about external actions and transform format are covered in Eraspaas Programming Guide.
More Action Order and Dialog URL
With On Demand option it is can also specify the position at which the On Demand action is available in the more actions dialog by providing more action order. Further with some On Demand action it is also required to take additional input from users before the action can be triggered such on demand action can have dialogs which are html pages attached to any web folder. In case when Dialog URL is provided then the corresponding html dialog is shown instead of directly triggering the action with the record information. Example of such action with Dialog URL includes, Import Data, Export Data, View Report, etc.
A Solution is a collection of records of System and UI entities. This allows grouping system entities/records into a package so that a solution can be easily exported from one domain and imported into another domain. Further it allows removing an application from a domain similar to uninstalling an app, that is when a solution is removed all related entities, attributes, relations, etc. are also removed from the domain along with the solution.
A solution can be locked or unlocked, by default all solutions are unlocked, however in order to prevent incorrect updates on solution records (example if a code has been programmed against a specific entity 'Test Entity' and its attribute 'Test Attribute', then the user should not be able to modify system information of this entity or attribute). So a locked solution prevents incorrect updates by user to the corresponding solution records, however locking of solution can only be done when it is being exported.
The above screen shows the Solution form.
Besides the above defined entities of the Eraspaas system that enable designing and deploying solutions. The following additional system entities provide extended features:
Web folder is a system entity that represents folder on the server. Although every entity and each record has a server folder assigned to it to store attached documents. However web folders are entities designed with the sole purpose of containing documents also allowing creation of logical hierarchy of web folders. Another special treatment for web folders is that the attached files/contents of a web folder related to a solution are also packaged with the solution.
6.2 Emails, Users and Departments
Unlike records of other system entities; records of Emails, Users and Departments are not packaged with solutions, this is because records of these three entities are understood as data which is specific to domain and not a meta-data that defines any component of the solution. However such records can be migrated from one Eraspaas domain to another through Export Data and Import Data actions.
Emails
With every domain registered at Eraspaas a dedicated mailbox is created through which emails can be sent and received from the system to other email addresses. The default email address of every domain is in the form of <domainname>@eras.in, so any email sent to the domain email address is recorded into Eras system, further all emails sent from the Eraspaas system is sent from the same domain email account.
Note: based on platform service subscription level it is also possible to change the domain email address to any other email address of a mail server that supports SMTP and IMAP protocols.
Users
Any person that has access to data in a specific Eraspaas domain is recorded as a user in that domain; also the first person who registered the domain is made a Main Admin of that domain. This allows him to configure the system and create other users in that domain with specific privileges. Further open registration can also be enabled through a public site of the domain that allows internet users to register through external systems like facebook, google or directly at Eraspaas system.
Note: based on platform service subscription level it is also possible to create users from the company's directory service (active directory) system.
Departments
Department allows organizing users into hierarchical structure of departments (divisions or business units) of an organization.
Note: more details about users and departments are covered in "Eraspaas Security, Abstraction and Identity" document.