User Guide: Getting Started

Login to Data Façade

After installing Data façade, you can access the configuration pages via Internet explorer on the following url

http://<host>:<port>/WebDB
e.g. http://localhost:8080/WebDB



The login page will appear. Select Manual Login, and enter the user id and password.
Note: Automatic Sign In is for NTLM enabled systems.

For the 1st time login use the built in admin account.

User Id: admin
Password: Go4Gold

Note: After Initial login please change the admin password to some thing else

Creating/Managing Roles

1. Login to Data Façade using an "Admin" account. Select Config->Security->Roles from the tree menu on left hand side.

2. The "Roles" page will be open. You can select a specific role, and edit the Name shown on the right hand side panel. Click "New" button to create a new Role, and provide the Role Id and Name and click Save.



Note: When you click "New" on a "Child-less" DB Object like this, it goes to the insert mode and you can keep adding entries.
When creating new DBObject, you can specify these roles to restrict access to it.

Create/Manage Users.

1. Select Config->Security->Users

2. Users page will be displayed, Showing a list of existing users, and information about the selected user. Pick the user you want to manage, and the general information about that user will be shown. Also notice the "Child" DB Object showing the "Role Assignments" of the selected User. You can add more roles to a selected user by clicking the "New" button under Role Assignments, and selecting the Role, and "Enabled" status.



Note: These Roles are populated from the Roles created in the previous exercise.

3. To add a new user, click "New" button under User DBObject and provide the information on the right hand side panel. You can also select an existing user, and then use the Clone tab to clone a user with similar properties of the selected user with a new id.

Create/Set Configuration Parameters.

Certain Configuration parameters are used by built-in features of Data Façade. They you can add new configuration parameters to be later used by custom "Actions"

1. Select Config->Initial Setup->Config Params. "ConfigParams" page will be displayed. Pick a parameter to be modified, or add a new parameter by clicking "New"

Note: There are few built in parameter

com.liqfy.config.homePage.title	The title of the browser windows (HTML Title tag)
com.liqfy.config.homePage.greeting	The "Greeting Message" on the login page.
com.liqfy.config.menubarMessage	The standard message to be displayed on the main "Tree" menu.
com.datafacade.licensekey	The License Key. Replacing the license key with a valid prodction license removes Trial teasers.

Configuring Data Sources

Data Sources represent the database connections of the data exposed by Data Façade. You can have any number of data sources defined. During Creation of DB Objects, you will be specifying "Primary" table of any of the listed Data Sources here. Data Facade can access any database which has the JDBC (fully compliant) driver. Out of the box Data Facade ships Oracle, MS SQL Server, DB2 and JDBC-ODBC bridge. For any other database, please copy the appropriate driver jar files to the tomcat classpath (i.e. common\lib) of the Data Façade home.

1. Select Config->Initial Setup->Data Sources. Data Sources page will be displayed.



2. Select the data source to be configured or click "New" to add new data source. Provide the JDBC Driver name, the connection url, user id, password pool size testing interval and test query.

Oracle

Driver: oracle.jdbc.driver.OracleDriver
Connect String: jdbc:oracle:thin:host:port:SID
MS SQL

Driver: net.sourceforge.jtds.jdbc.Driver
Connect String: jdbc:jtds:sqlserver://hostname:port/databaseName
DB2

Driver: com.ibm.db2.jcc.DB2Driver
Connect String: jdbc:db2://hostname:port/databaseName
JDBC-ODBC Bridge

Driver: sun.jdbc.odbc.JdbcOdbcDriver
Connect String: jdbc:odbc:odbcName
Click "Insert" (or "Save" if this is a modification to an existing data source) to save the changes.

3. Click "Meta Data/Test" button to test the connection. If successful you will see a list of objects (Tables/Views etc) available in the data source. You can further investigate the metadata data by selecting table objects (checking the check boxes) and clicking next.

User Guide: Applications

Data Façade hosts multiple applications. Each application consists of multiple DBObjects providing CRUD capability to underlying database tables and reports. Applications are declared by the administrator. Application logically groups related DBObjects and reprots together. Each Application entry is visible to end users (provided that they have rights) as a "Root" point in the Left hand side menu. When DBOjects or reports are configured the relative menu path is specified.

Managing Applications
1. Login as an Administrator.
2. From the main "Tree" menu, select "Config->Applications". List of applications will be listed at the main panel.
3. Select the application you want to manage. The application details will be displayed at the details panel to the right.
4. Click the "DBObjects" link to open up a list of DBOBjects associated with the application.
5. Alternatively you may click "New" to create new Applications.




Applications and their components are listed in the main menu.

User Guide: DB Objects

DBObjects are the core visual components of Data Façade. They provide web based CRUD interfaces to database tables. A DBObject (along with it's child components; DBColumns & Actions) represents visual and behavioural aspects of data entities.

NOTE: Management and Configuration of various elements (e.g. DataSources, Users, Roles, Reports, DBObjects) of DataFacade are DBOBjects them selves. We have used the rich featureset of DBObjects to boot-strap it self.

Managing DBObjects
1. Login as an Administrator.
2. From the main "Tree" menu, select "Config->Applications". List of applications will be listed at the main panel.
3. Select the application you want to manage. The application details will be displayed at the details panel to the right.
4. Click the "DBObjects" link to open up a list of DBObjects associated with the application. The list will pop-up in a new window.
5. Select the DBObject to be managed or Click "New" to create a new DB Object.
6. After modifying the properties click "Save" to save the changes.

DBObject Properties and their behaviour

Once you select a DBObject to edit (or click "New" to create), the properties of the DBObject will be listed on several "Tabs" as shown below. The tabs are logical grouping of related properties. You can hover the mouse on most of the property names to see a "ToolTip"

DBO Name
A unique name given to the DB OBject. This can only be specified during the creation of the DB Object. Name should be less than 255 characters.

Description
Textual description of the DB Object. Must be less than 255 characters.

Connection Name
Select the Data Source hosting the database table to be CRUD enabled.
These Connections are defined under;
         Config->IntialSetup->DataSources
from the main tree menu on the left.

Primary Table
Select the Database table to be CRUD enabled.
Note: System assumes the user account provided for the DataSource has sufficient rights to perform the read/write operations on this table

Date Format
Default date format for the Date fields in this table.
Note: Format is specified in Java style Date/Time formats

Page Size
Number of records to be displayed in a single page when browsing.
Note: Specify -1 to show all the matching records. However this is discouraged for large tables (i.e. >1000 records)

Keys
List of Keys (seperated by |) uniquely identifying individual records of the table.

Sort Columns
Column names to be used for Sorting (seperated by |). You may use SQL sort modifire "DESC" to sort in descending order.

Insertable
Check this box to allow users to create new records in the primary table.

Delete
Check this box to allow users to delete records in the primary table.

Cascade Delete
Check this box to delete the records from child DB Objects having Child-Parent relationship to this DB Object, when a record is deleted.

Clonable
Check this box to allow users to create new record by cloning the current record.
Note: User will have to provide new key values as prompted.

Print Preview
Check this box to allow users generate a Printer Friendly view of the selected record and it's child data entities.

onLoad
You can specify a Java (BeanShell) script to perform some custom tasks when record is loaded.
Implicit variable DB_RECORD can be used to access the data that was loaded (see the APIs of DBRecord).

onSave
You can specify a Java (BeanShell) script to perform some custom tasks when record is saved.
Implicit variable DB_RECORD can be used to access the data that was loaded (see the APIs of DBRecord).

onDelete
You can specify a Java (BeanShell) script to perform some custom tasks when record is deleted.
Implicit variable DB_RECORD can be used to access the data that was loaded (see the APIs of DBRecord).

Children display mode
Specify how the child records are displayed. This property is only applicable for DBObjects that specified as children to another DBObject.
Following samples shows results of each option (i.e. Cascade,Popup,In-Line Popup,Hidden) of this property.






Record display mode
Specify how the selected record (or new record to be created) is displayed.
Following samples shows results of each option (i.e. RHS,Popup & In-Line) of this property.





Record Search mode
Specify how the records are searched/browsed.








Height
Height of the data browsing area in pixels

Detail Panel Height
Height of the Detailed Panel where the record details (for the selected record) are displayed.
Note: This property is ineffective if the Record Display Mode is RHS

Detail Panel Width
Width of the Detailed Panel where the record details (for the selected record) are displayed.

List Panel Width
Width of the List (browsing) Panel where the records are displayed.
Note: If the record display mode is InLine, this width should be > Detail Panel Width

Window Height
Height of the new Browser Window created to display records. Only applicable when Children display mode is "Popup".

Menu Path
Menu Path to be show in the Main Tree Menu on the left to access this DBObject. This is a relative path, having application name as the base.
Note: For Child DBObjects (i.e. the DBOjects that will be listed as a Children in another DB Object) this property should be left blank.

Help File
You can upload a document (preferably a PDF or self containd HTML) which would be a online help/guideline for the end users using this DBObject. If a help file is specified, a "Help" button will appear on the top tool bar, that would open the file you specify when clicked.

Roles
Roles can be specified to restrict access to the DBObjects. Available options can be listed by hovering the mouse on the "eclipse" right above the Roles Text area. Each Roles optionally followed by it's access level are listed here in each row.

e.g.
Admin
CRM::R,L

Above entry means, Admin Role has full access and CRM Role has (R)ead and (L)ist access.

User Guide: DB Columns

DBColumns represents the visual aspects of the columns of underlying database table (the primary table associated with the DBObject). Based on the data type, enumeration and the formats, Data Façade automatically displays appropriate contorls to the end user. They also have built in validation functions such as data type validations and have provisions for custom client side validation thru java script snipets. Usually a DBColumn is directly mapped to a column on the primary table. However there are situations where "Artificial" DBColunns mapping to a computed field (e.g. Concatination).

Managing DBColumns

1. Open the DBObject to be managed (or Create a new DBObject and save changes).
2. Click the "Columns" link to open the list of Columns.
3. For each Column listed modify necessary properties by providing appropriate values. Make sure you save the record before moving to the next.

DBColumn Properties and their behaviour

Once a column is selected to be modified, properties associated with it are shown in multiple tabs as shown below.


Demo/Tryout field edit window

Name
Column name. During the Creation of the DBObject this value is auto populated. However you may change it to a calculated field.

Description
This will be displayed to enduser as a the label for the field. Default is the Column name it self.

SQL Type
Select the Data Type. This is also auto populated during DBObject creation.

Lookup
Lookp is an optional field to specify a list of values to the end user. When a lookup is specified end user will see a "Drop Down" or a "Combo Box".
A Drop Down will be shown if this field is NOT Nullable. Otherwise a Combo Box will be shown.

There are three ways to specify a lookup

NOTE: You can see these options and copy a "template" of them to this field by hovering the mouse over the "eclipse" on the left/top corner of the input field, and then click on any of the values (You can try it on the demo field edit window shown above).

Default Expression
A Java Expersion that would result a "default" value for this field. You may specify a fixed string using double quotes (e.g. "My Default").
Some other usefull values are
Note: There are short forms listed in the guide box that pops up when you hover the mouse on the top/left corner of the field (You can try it on the demo field edit window shown above).

Validator
A custom Java Script to perform client (Browser) side validation. There are few convenience built in java script functions that can be utilized in this script to reduce the coding effort.

Note: There are short forms listed in the guide box that pops up when you hover the mouse on the top/left corner of the field (You can try it on the demo field edit window shown above).

Enumeration
Provides a vay to specify a "Fixed" list of values for the field. The enduser exprience is two fold. If Enumeration values are provided and "Enum" is specified in the "Lookup" property, it will show a Combo Box or a Drop down. If the "Lookup" proprty is blank, it'll show a list of "Radio Buttons" to pick.

Enter enumeration in following formats

1. key1::value1|key2::value2
2. value1|value2

Foreign Key
Used when this DBObject is a child of a parent DBObject. Specify the name of the Foreign Key field of the Parent DBObject relating to this DB object.


Format
Format of the field. Format can be specified in different ways and based on that the control shown to the end user will be different.


Group
Group provides a way to logically group fields in to different tabs when they are show to the end user. Each unique group name specified in the list of columns shows a seperate Tab to the end users. If a group name is not specofiec for certain columns (and group names are specified to some others) those columns without group names will be automatically assigned a defualt tab "General Info".

Note:
Order of the tabs are decided by the "Display Order" of the columns in the group.

Use of special group name "_head" makes the fileds to apear above the tabs, so they are always visible irrespective of the tab selected.
Use of special group name "_foot" makes the fileds to apear below the tabs, so they are always visible irrespective of the tab selected.


Display Order
The order in which the controls are displayed in the ascending order.

Horizontal Position
Used when more than one field to be displayed in the same vertical (row) level (i.e. having same display order in the same group). In such cases fields will be displayed left to right in the ascending order of this value on each field.

Packing Policy
This specifies how the fields are packed horzontally if they share the same display order (see Display order and Horizontal position).

Remarks/Tooltips
Specify a user friendly remark/tooltip for this field, that would be displayed to the end user when the mouse is hoverd over the label of the field, in form of a tool tip bubble.(You can try it on the demo field edit window shown above, on any of the fields that have "active" label)

Listable
Specifies wheather or not this field is listed when records are browsed.

Listable
Specifies wheather or not this field is visible when a selected record is shown.

Listable
Specifies wheather or not this field is editable when a selected record is shown.

Nullable
Specifies wheather or not this field can be null.

Filterable
Specifies wheather or not this field can be used in a Filter to short list records that are displayed during broswe. Filterable fields will be listed when the "Filter" button on the record browse page is clicked.

User Guide: Actions

Actions provide extension capability to Data Façade. With Actions you can provide custom code that get executed when invoked thru buttons. Actions have 3 different levels of scopes, namely "Global","Record" & "Validation". These will be further discussed under properties of Actions. Similar to DBColumns, Actions are associated with specific DBObject. A action can have set of runtime parameters that would require end user to provide values during execution of the action.

There are three types of Actions.

1. Generic Action: In Generic actions administrator has to provide a "Bean Shell" script during the configuration of the action. Optionaly provide a script to generate a lit of runtime parameters.

2. Custom Actions: Developers create a custom java class extending "Action" class and add that to the classpath. This requires a restart of the Data Façade (i.e. restart the hosting tomcat instance) for these action to register.

3. Java Script Action: These are actions that get executed on the Browser Side. Administrator specifies a Java Script during the action configuration.

These types are further discussed with samples later.

In case of type 1 and 2, the results of the action can be later obtained (by a JSP implementing the "View") via following Session variables.

ACTION_MSG: String message set by the action
ACTION_ERROR: String Error message set by the action
ACTION_ALERT: String Alert message set by the action

Actions (type 1 and 2) can have a workflow associated with them. The Action implementation will return a status number, and based on that number you can specify a url (usually a JSP page) to be called to show the out come of the action. This outcome may be show on a seperate window or the same window where the record is shown.

Managing Actions

1. Open the DBObject to be managed (or Create a new DBObject and save changes).
2. Click the "Actions" link to open the list of Actions.
3. Pick the Action you want to manage or click "New" to create a new action.

Action Properties and their behaviour

Once an Action is selected to be modified, properties associated with it are shown in multiple tabs as shown below.


Demo/Tryout Action edit window

Name
Name of the Action. This will be shown to the end user as a button.

Description
Description of the action. Reference purposes only.

Action Class
Pick the appropriate action class.
Select com.bgs.db.events.GenericAction to pick a generic action and then provide a Java Bean Shell script to implement the action logic.
Select javascript to provide a client (browser) side action on which provided java script will be executed.

Based on the action class selected, there will be diferent configuration options which would be avialabe after the Action modifications are saved.
Note: The dropdown will list all the classes extending "Action" class in the classpath. Some of them are Data Façade specific system actions.

Scope
Scope of the Action.



Action Type
Wheather the action is read-only or not. When an action is marked as Read-Only, endusers do not nead update rights to invoke those actions. If the action type is Default, the action will only be avialable to users with update rights to the DBObject.

Display Order
Order in which the Action buttons will be shown to the end user.

Icon
A small image file (.gif or .jpg) may be uploaded to be used as the icon for the action.

Confirm Message
A confirmation message tobe shown to the enduser upon clicking the Action button, to makesure if the action was intentional.

Target Window
A window name and it's properties on which the results of the action will be displayed.

<window_name>[:<window_properties>]
e.g.
1. ResultsWindow:menubar=0,toolbar=0,location=0,status=0,scrollbars=1,width=800,height=800,resizable
2. ResultsWindow

Forwarding
Used to specify custom views (jsps) based on the status of the action.
<status_code>::<view_jsp>
e.g.
    0::Sucess.jsp
    1::WF_1.jsp


Failure Page
Used to specify custom view (jsp or html) for failures


After Saving the "Action" Click "Configure" to open the custom configuration window for Action specific configuration options.

Code Samples

1. Generic Action

In generic actions, the administrator specifies a Java Bean-shell script to be executed when invoked. This script is specified during the "Configuration" of the action.

Following sample, obtains the value of "DEPARTMENT" field populated by the end user, and queries the EMPLOYEES table to get the list of empoyees in that department and send their Ids and Names in the format of id1|id1..idn#name1|name2..namen

Note: This is be used as a validation function where after selection of department, the employees of that department will be listed for subsequent select.

String department=DB_RECORD.getData("DEPARTMENT"); StringBuffer ids=new StringBuffer(); StringBuffer names=new StringBuffer(); Object[][] data=com.bgs.db.ConnectionManager.getInstance().getData("DemoDB","SELECT EMP_ID,LAST_NAME||','||FIRST_NAME||' '||MI FROM EMPLOYEES WHERE DEPARTMENT='"+department+"'",2); for (int i=0;i<data.length;i++){ ids.append("|"); ids.append(data[i][0]); names.append("|"); names.append(data[i][1]); } if (ids.length()>0){ ACTION_MSG=ids.toString().substring(1)+"#"+names.toString().substring(1); }else{ ACTION_MSG=""; }

Note: The validation function (java script) associated with DEPARTMENT field to use the above action, is show below. It sets the List Of Values to the list returned from above action. See "Validation" property for DBColumn.
callAction, and setList are built-in convenient Java Script functions.


2. Custom Action

Custom actions are the java classes written by developer and added to the classpath (Usually jared) of the hosting web server (i.e. tomcat). Custom java classes provides the most flexibility.

Following sample, Converts the data represented by the DBObject into an XML. If a Style Sheet is provided in the Action Configuration, it will be applied.

package com.bgs.db.events; import com.bgs.db.*; import java.util.*; import java.sql.*; import com.bgs.util.StringTools; import org.jdom.*; import com.bgs.util.XMLTools; import java.io.FileReader; import java.io.*; import javax.xml.transform.*; /** * <p>Title: BuidXMLView </p> * <p>Description: Builds XML view of the data</p> * <p>Copyright: Copyright (c) 2008</p> * <p>Company: DataFacade</p> * @author Buddika Gajapala * @version 1.0 */ public class BuidXMLView extends Action { /** * Performs the BuildXMLView Action. Uses the stylesheet specified at the config time. * @param dbr * @param params * @return */ public int perform(DBRecord dbr, Properties params) { DBObject dbo=dbr.getDBObject(); Document doc=new Document(); Element root=new Element(dbo.getName()); doc.setRootElement(root); String styleSheet=params.getProperty("StyleSheet"); DBColumn cols[]=dbo.getDBColumns(); HashMap groupElements=new HashMap(); for (int i=0;i<cols.length;i++){ String groupName=(cols[i].getGroup()!=null && cols[i].getGroup().length()>0 ?cols[i].getGroup():"GeneralInfo").replaceAll("[^A-Za-z0-9]","_"); try{ Element groupElement = (Element) groupElements.get(groupName); if (groupElement == null) { groupElement = new Element(groupName); groupElements.put(groupName, groupElement); root.addContent(groupElement); } Object data=dbr.getData(cols[i].getName()); if (data!=null){ data=cols[i].getLookup()==null?data: cols[i].getLookup().lookupValue(data.toString()); Element colElement = new Element(cols[i].getName()); colElement.setText(data.toString()); groupElement.addContent(colElement); } }catch(Exception e){ e.printStackTrace(); } } XMLTools xmlTools=new XMLTools(); String xml=null; if (styleSheet!=null){ if (styleSheet.startsWith("http")){ HashMap piMap = new HashMap( 2 ); piMap.put( "type", "text/xsl" ); piMap.put( "href", styleSheet ); ProcessingInstruction pi = new ProcessingInstruction( "xml-stylesheet",piMap ); doc.getContent().add( 0, pi ); xml = xmlTools.documentToString(doc); }else{ try { xml = xmlTools.documentToString(doc); xml = xmlTools.applyStyleSheet(xml, new FileReader(com.bgs.util.Config.EXTENSION_RESOURCES_FOLDER+"/"+styleSheet)); } catch (FileNotFoundException ex) { } catch (TransformerException ex) { } } } params.put("$ACTION_MSG",xml); return 0; } /** * List the configuration parameters. In this case a single configuration parameter expecting an optional text value for the Style sheet * @param dbr * @return list of DBColumns showing the configuration parameters. */ public DBColumn[] getActionConfigurationFields(DBRecord dbr){ String params=(String)dbr.getData(DBObjectFactory.META_DBA_PARAMS); DBColumn fld[]= new DBColumn[1]; fld[0] = new DBColumn(super.ACTION_PROP_PREFIX+"StyleSheet", "Style sheet", Field.COL_TYPE_STRING, true, true, true, true, "", null); fld[0].setFormat("x:40"); fld[0].setRemarks("Provide the name of the style sheet as a url or name.<br>"+ "If you proivde a file name make sure that file is located at "+ "bin/LiQfy/ExtResources"); return fld; } /** * The default window options, this will show the resulting XML in a new browser window names XMLview. * Note: This value may be overidden in the Action definition under window options. * @return windowOptions */ public String getWindowOptions(){ return "XMLview:menubar=1,toolbar=1,location=0,status=0,scrollbars=1,width=800,height=800,resizable"; } }

3. Wizard Action

Wizard actions are specilized Custom actions. Unlike simple actions, the Wizar Actions have more than one page and end user is guided thru the action states untill finished. Wizard Actions extend WizarAction class. See the API dicumentation for details.

User Guide: Reports

Data Façade provides simple yet powerfull reporting capability on database tables. A report may be based on a Tabel/View or a SQL statement. Similar to DBObjects, Reports are bundled with the "Application", and made avialable to the end user (with appropriate security) as menu items. During the configuration, the administrator would specify the set of stadard properties and then go thru a configuration wizard.