This document will give you an overview of the Ebase system. It describes all the major concepts and facilities available without going into too much technical detail. It is designed to give you a good basic understanding of the capabilities of the system.

Ebase Designer

The Ebase Designer is a client/server application where the client component is a standalone Java GUI application and the server component is a J2EE application that runs under an application server. This architecture supports any number of concurrent designers. The client is the major component calling on the server to provide support and control functions. The designer server component functions include:

· reading and writing data to/from the Ebase repository database

· locking of Ebase Designer elements to maintain integrity

· security

· import and export of form components

Designer screen layout

The Ebase Designer layout consists of three areas:

· Main menu at the top of the screen.

· Hierarchy tree at the top of the left panel. This is used to navigate to all form components.

· Functional area in the right panel. The contents of this panel vary according to the type of element being worked on.

· References panel at the bottom of the left panel. Contains cross reference, search panels etc.

Organization of elements

Ebase consists of a number of different element types e.g. form, script, list etc. and these all interact to produce a fully functioning form. These elements are organized into a hierarchical structure which, at the top level, consists of:

· Business projects: a project consists of forms, scripts and messages. The scripts and messages are shared by all forms within the project, but cannot be used by forms in a different project.

· IT elements: this consists of all external resource definitions (database resources, email resources, MQ resources etc) plus business views, dynamic lists and databases. All elements in this part of the hierarchy can be shared by all forms.

· Shared elements: this consists of browser presentation templates and static lists. All elements in this part of the hierarchy can be shared by all forms.

· Workflow: this contains workflow processes and workflow activity definitions. It is only visible when the Ebase Workflow module is installed.

· Integration Server: similar to Business projects, this contains implementations of published web services. It is only visible when the Ebase Integration Server module is installed.

(See Ebase Element Types for more information)

Basic designer tasks

To open an element, navigate to it using the hierarchy tree, then double click on the element name. Note that it may take a couple of seconds to load the element from the server. Once opened, an element remains active in Ebase Designer until it is explicitly closed. In a multi-user environment, the element is also locked and cannot be worked on by other designers until it has been closed.

To close an element without saving it, close the containing frame or select close on the local function menu (rightmost menu item).

To save an element, select save on the local function menu or click the Save button within the function editor. All elements must be explicitly saved.

To create a new element, right click in the hierarchy tree at the appropriate location and select Create new ; or select an element type from the file menu (File --> New --> ….)

To delete an element, right click on the element in the hierarchy tree and select delete or select the delete option from the local function menu (rightmost menu item).

To copy an element, right click on the element in the hierarchy tree and select copy.

To rename an element, right click on the element in the hierarchy tree and select rename.

To move element(s) to another project, right click on the element(s) in the hierarchy tree and select move.

To obtain a list of references to an element, right click on the element in the hierarchy tree and select References.

Basic building blocks

A business project contains any number of forms, scripts and messages. The scripts and messages in a business project can only be accessed from forms within the same project, i.e. sharing of these elements across projects is not supported. An exception to this rule is the special GLOBAL project which contains scripts and messages available to all projects. The GLOBAL project also contains components that can be included in any form.

An Ebase form consists of two major elements: pages and fields.

The system will display each page to the user, validating each one in turn, until there are no more pages to display. It will then perform any final form processing and optionally display a final page to the user. This final page typically contains messages relating to the success or otherwise of the form e.g. Thankyou for your application. Please quote ref 123456 in any future correspondence. The sequence in which pages are displayed is initially set by the forms designer, but is entirely dynamic - i.e. it can be changed at runtime depending on data entered by the user or any other circumstances. So pages can be skipped or re-displayed as required. Such changes are performed using a script which is associated with an event (more on this shortly).

Each form will contain a number of fields. A field can have many attributes e.g. name, value, type, label text, help text.... and many more. It is important to realize conceptually that a field is maintained at form level by the system, as opposed to at page level. This means that the field value and its attributes can be referred to and changed at any time during form processing.

When a field is placed on a page, it has additional local attributes referred to as control attributes e.g. mandatory, hidden, display only, validation etc., and these attributes can also be changed dynamically using a script.

Fields can also be displayed in tables where each table consists of a number of rows each containing column fields. Tables are configured in the Designer as shown in the example below:

The process of building a form initially consists of constructing these main elements and then setting the attributes for each. This process is reflected in the Ebase Designer.

Event handling and scripts

Events are points within the processing flow of a form e.g. on click event for a button.

Scripts are programs written in Form Processing Language (FPL) which is a scripting language with English-like syntax.

Scripts are configured to execute at one or more of the events, and this provides provide the ability to add programming logic to form processing. Scripts can be used for all kinds of purposes including validating user input, dynamically changing which pages and fields are displayed, interfacing with external resources e.g. to read and write from databases, sending emails etc. The system supports a total of 15 events, of which the most important are shown below with some typical uses for each event:

Event	Typical Use
Form Events
Before Form	To perform any preliminary processing before the first page is displayed to the user e.g. load information from a database or some other external system.
After Form	To perform any final processing: this might include inserting database records, sending emails, preparing messages to be displayed on the form's final page etc.
Page Events
Before Page	To perform any preliminary processing for the page e.g. loading database data, displaying or hiding fields, making fields display only or enterable etc.
After Page	To perform page level validation or cross field validation; to set the next page.
Field Events
Validation	To perform field validation.
On Click	Used to perform specific processing when a button or hyperlink is clicked.
On Change	Used to perform specific processing when the user changes the value of an immediate validation field.
Table Events
Before Table	To load a table from a database or from an XML document; calculate totals fields etc.
Add Row	To initialize values for a new table row.

See Understanding Ebase Events for more information on events.

The FPL script language has an English-like syntax.

Here is a simple example to check some entered data and display an error message to the user:

if [ PHONE_NUMBER = '' and EMAIL_ADDRESS = '' ]

message E, 1012;

endif

In addition to these commands, the language can be extended to call user-written functions, thus adding the ability to call external components. An example of this might be:

if [ check_creditlimit(DEBIT_AMOUNT) ]

endif

where check_creditlimit is a function that accepts 1 parameter - the amount of the current transaction which is contained in form field DEBIT_AMOUNT, and returns true or false.

(See FPL Script Commands Syntax for more information)

Multiple language support

An Ebase form can be designed once and then run in any number of different languages. To enable this, all texts and messages can be entered in multiple languages. At runtime, the user’s language preferences as configured in the browser can be used to set the language. Alternatively, a default language can be used, with the possibility of overriding this by adding the parameter LANGUAGE to the invoking URL. For example, the following URL could be used to invoke a form in French:

www.myco.com/ufs/ufsmain?formid=MYFORM&LANGUAGE=FR

The Ebase Designer allows multilingual texts and messages to be entered. Each designer user has a default language which can be changed as desired.

(See Internationalization Support for more information)

Dynamic form texts

All form texts can contain substitutable variables which are dynamically substituted at runtime. For example, form text:

Department &&DEPT, expenditure for &&YEAR

is displayed as:

Department Personnel, expenditure for 2005

if field DEPT has value 'Personnel' and field YEAR has value '2005'.

Messages

A message is a piece of text (language dependent) which can be sent to the user programmatically when certain conditions arise. The script command to send a message is :

message type, number, [parm1, parm2,......]

The system supports 3 types of message as specified by type:

E	error message
W	warning message
F	information message to be be displayed on the final page

error messages are by far the most common type and will result in an error message being displayed immediately above the field where the error was detected. When a script issues an error message, form processing stops immediately and the page is re-displayed to the user with the error message. The user must correct the error to proceed. The foreground and background colours can be changed to ensure the messages are clearly displayed.

warning messages are similar to error messages except that form processing will not stop. Warning messages must be acknowledged by the user. As with error messages, the foreground and background colours can be changed.

final page messages will be displayed on the final page that is displayed after form processing has completed. They normally contain information about what the form has done and feedback information on numbers of records created e.g. order numbers etc.

All 3 types of message allow form field values to be substituted into the message text. For example, if message 1234 contains text:

"You cannot order && with &&"

and a script contains command:

message E, 1234, EXTRA_ORDER_ITEM1, MAIN_ORDER_ITEM;

then the user may get a message saying:

"You cannot order ketchup with caviar"

(See Working with Messages for more information)

Page navigation buttons

Ebase supports next and previous page navigation using page buttons. An additional finish button can be displayed if the page being displayed is the last page. On the final page, a return button can be used to take the user to a specific URL e.g. return to a menu page or home page, run another form or even re-run the same form.

The forms designer has full control over the appearance of these buttons: he/she can choose whether to use normal buttons or special images, can control the texts displayed, can hide or display the buttons at runtime or change the texts.

Save and restore

In addition to the navigation buttons described in the previous section, 2 additional buttons save and restore can be displayed. These provide the end user with the ability to interrupt (save) what they are doing - for example, to find a piece of information asked for by the form - and then continue (restore) at a later time or date. This feature can be enabled or disabled at form level and the forms designer also has control of the appearance of the buttons, the texts etc. Optionally, the end user can be prompted to enter a password when saving, and then this will be checked against the corresponding password during restore processing.

(See Save/Restore for more information)

Lists

A list gives the user a choice of selectable values that would normally be displayed as a dropdown list, although Ebase will also support displaying a list as radio buttons or as checkboxes. Once a list is defined and associated with a field, the system will automatically display the list values. Ebase supports 2 types of list:

A static list contains language dependent values which change only rarely. An example of this might be title containing English values: Mr, Mrs, Ms, Miss, and French values : M, Mme, Mmle.

A dynamic list represents a list of values which will be read from a relational database. These lists are not language dependent. To configure a dynamic list, the forms designer must specify the database table(s) and column(s) and optionally the WHERE clause to be used. Ebase supports complex SQL constructs involving views, joins etc.

In addition, Ebase provides some additional features that can be used with lists:

For very long lists where it is not practicable to download all list values, the list can be used as a validation mechanism where the user enters a value and the system checks whether the entry exists. Handling of not found conditions can be done automatically by the system or can be handled by a script by checking system variable $FOUND which will contain 'Y' or 'N' after the list has been validated. The list will automatically operate in this validation mode when it is associated with a text entry field as opposed to a dropdown list, radio button, or checkbox.

For dynamic lists, additional database columns can be retrieved and mapped to form fields. For example it is quite useful to be able to display something meaningful to the user such as product names, and then automatically populate an additional form field such as PRODUCT_ID with a numerical value, which is of no interest to the user, but of plenty of interest to the form designer.

(See Working with Lists for more information)

Action buttons and hyperlinks

Any number of action buttons can be added to a page. When clicked, the FPL script(s) associated with the button's on click event are executed. For example, buttons could be used to update a database, display a different page with an expanded view of a selection, send an email etc. A hyperlink has the same functionality as an action button, but allows the action to be associated with a form field variable e.g. an order number might be displayed as a hyperlink where clicking the link displays the order detail.

Immediate validation

Generally, the Ebase Server component receives control whenever a user clicks on a button or a hyperlink. In addition, it is sometimes desirable for the server to receive control immediately when data is entered in a particular field, and then run a script to process the entered data e.g. to fetch information from a database, or to hide or show additional fields. This requirement is met by setting the immediate validation flag for a field.

This is best illustrated by a simple example. Say we wanted to give the user a series of address related dropdown lists, the first being country, the second region, and the third city or town. We would like the user to first select a country, then select from a list of regions within that country, then select from a list of towns and cities within that region. This 'linked list' type of processing can be accomplished in Ebase by building 3 dynamic lists for country, region, and town/city and associating them with the 3 form fields, and then setting the immediate validation flag for the country and region fields. Thus when the user selects a country, the system will then return with a list of regions - it will ignore the town/city list at this time as it will recognize that all required fields (region) are not available to build the list values. The user will then select a region and the system will finally build the town/city list and display this to the user.

Components

A component is a subset of a form and can include fields, pages, FPL scripts and resource mappings, A component can exist independently of a form, but can be linked to any number of forms. A simple example might be an address component which could contain all the usual address fields plus FPL scripting logic to perform a postcode lookup and populate all the address fields from this. Rather than create this in every form where it is required, it can be created just once as a component then linked with any number of forms.

(See Working with Components for more information)

Tables

A table represents an array of data values that can be displayed in a tabular format as shown in the example below.

The main features of tables are:

Table data can be loaded from and saved to an external resource such as a database
Table appearance can be fully customized
Table rows can be updated, deleted and inserted by the user or programmatically using FPL
An optional select column can be added as the leftmost column to support programmatic row selection
All entered data can be validated using after field events in the same way as for non-table fields
Tables can contain a mixture of resource and non resource fields
Tables can contain lists
A table can be sorted on any column, ascending or descending
Tables can be scrolled both vertically and horizontally
Tables can contain fields of any type

(See Working with Tables for more information)

Page processing and Control fields

A form may contain 2 types of fields. Display (normal) fields and Control fields. A control field is a field which is never displayed. The only purpose of having a control field is to associate script(s) with it.

As stated earlier, Ebase Server receives control whenever a button or hyperlink is clicked, or when data is entered in an immediate validation field.

Page processing is performed whenever a next page button is pressed, a finish button is pressed, or data is entered in an immediate validation field. During page processing, 'every non-hidden field' on the page is processed, in sequence, except when an immediate validation field triggers page processing, in which case processing stops on that field. 'Every non-hidden field' includes control fields (which are permanently hidden fields), if any.

Processing a field effectively means running script(s) associated with the field, or validating the entered data against a list, or both. Each field is processed in turn until all the fields on page have been processed or an error is encountered.

Browser presentation basics

The following diagram shows the basic layout of an Ebase page. Fields are presented in a tabular display to ensure vertical alignment. The figure below shows a simple single column layout, but Ebase also supports a two column layout where fields can be presented on both the left and right side of a page (See Form Page Layout for more information)

There are many options to allow for customization of the presentation - more than can be included in a brief overview document like this. For example, all colours, fonts, font sizes, alignments, etc. are configured using a presentation template which is then associated with the form. Column widths are specified by dragging a slider bar in the form designer. The best way to find out what options exist is to use the Ebase Designer and experiment. The presentation template editor contains a test button which can be used to immediately see the effects of your changes.

All texts can be entered in multiple languages, can be of any length, and are optional i.e. they can be omitted.

At first glance the layout appears quite complicated, but is fairly simple when broken down into its constituent parts:

The form header is typically a one-line description of the form. If present, it will also contain small page navigation buttons on the right-hand side. These help the user page backwards and forwards without the need to scroll to the bottom of the page.

The page header is typically a one line description of this page.

The page information text provides an area where the forms designer can place general descriptive information about the page. This can be as long or short as is required.

The fields-on-page can optionally be placed into field groups (there are 2 field groups in the example above). Groups allow visual separation of related fields from other fields on the same page. Each group can have 3 texts associated with it :

field group header is typically a one-line description of the group e.g. Address.

field group information text provides the opportunity to insert a description of the group, or possibly instructions for the user on how to complete the fields.

field group trailer text is similar to the information text but is placed at the end of the group.

page trailer text is also similar to page information text but appears at the bottom of the page.

field label, field element, and field information are normally presented in a tabular format to achieve alignment and visual tidiness - each line in the table representing a single field. Field label is normally a description of the field, and field information provides the opportunity to provide some additional information - help text - about the field. This basic line layout can be customized in a number of ways:

· the relative widths of the 3 elements field label, field element, and field information can be changed

· the field information can be presented in 3 different ways - to the right of the field element (as shown above), as a button which then launches a pop-up window containing the text, or underneath the field element

· more than one field can be included in a line as shown in this example

Adding look and feel

Ebase provides many options to customize presentation and is flexible enough to adapt to any corporate look and feel. As described in the section above, most of the customization is done by changing options in the presentation template associated with the form. A number of templates are provided with the system, but these are intended to be examples which can be used to build additional templates customized to the requirements of a specific organization.

In addition, each form page can be surrounded by up to four JSPs (Java Server Pages) or HTML pages. These JSPs are not strictly part of the form, but they can access form data e.g. the current page name, field values etc. Some typical uses for these JSPs are:

· contain images and menus to make the page consistent with corporate look and feel

· contain progress trackers indicating which page the user is on, total number of pages etc.

· contain related links, additional information etc

The use of all four JSPs is demonstrated by the sample form MORTGAGE_APPLICATION. To run this form, start the Ebase Designer, navigate the tree hierarchy (Business Projects --> SAMPLES --> Forms), then double click on MORTGAGE_APPLICATION to load the form from the server component (this may take a few seconds the first time you do it), then click on the Run button on the form toolbar.

Lastly, it is possible to embed HTML tags in Ebase texts or field values. This gives the ability to fine-tune the appearance of individual items within the main form display. For example, it might be desirable to highlight a certain field by changing its colour, or to embed an image or a link to another part of the website.

Connecting to external resources

Ebase supports a number of external resources: databases, email, MQSeries, XML, Web Services. What these external resources all have in common is that they have the capability of interchanging data with Ebase form fields. The Ebase view of these resources is that they consist of a number of resource fields, and then these resource fields can be mapped to form fields. The interchange of data between an external resource and a form is under the direct control of the forms designer and is controlled using a number of script commands e.g. FETCH, INSERT, READ, WRITE, SENDMAIL etc. The Ebase framework for handling external resources is shown in the following diagram:

The Business view acts as a logical link between the form and all external resources to which the form has access.

Databases

Ebase supports access to any relational database that can be accessed via JDBC. This includes all commonly used databases.

Conceptually, this works as follows: the form designer first creates a database definition - this represents Ebase's channel to the database and contains the JNDI lookup name for the datasource as defined in the J2EE application server. The designer then creates a number of database resources (or stored procedure resources), each one of which represents a single SQL statement (or a single call to a stored procedure). Each database resource contains a number of resource fields that represent the columns in the SQL statement. Once the database resource has been constructed, the resource fields are mapped to form fields. Finally, script commands are used to read and write data to and from the database.

Ebase allows all of the steps above to be performed manually, but also provides tools to automate most of the process. Once the database definition has been set up and connectivity tested, database resources can then be imported directly from the database where each Ebase database resource represents a table within the database. This will import all columns of the table together with the column types and lengths. The only time it is necessary to build database resources directly is when more complex SQL is required e.g. table joins, views etc.

Once the database resource has been defined, the resource fields can then be imported directly into a form. This process will create the form fields and set the field types and lengths correctly. For example, if a numeric database field is defined with length 6 and 2 decimal digits, it is important that this information is used at presentation time to stop the user entering data that would be rejected by the database - in this example, a number with more than 6 digits are more than 2 decimal digits.

As with dynamic lists, information entered by the user can be mapped to fields in the SQL WHERE clause.

(See Working with Databases for more information)

Email

The Ebase email adaptor allows an email to be sent as part of form processing. Values from form fields can be substituted into the email message, the message subject, addressees etc. The basic concepts and flow for email are very similar to that of databases described in the previous section. The designer creates an email resource that represents a single email message. This resource can contain resource fields that are then mapped to form fields. Finally, the message is sent using the script sendmail command.

The only configuration necessary to enable email processing is to set the hostname or ip address of the email server in the Ebase properties file.

(See Working with Email for more information)

XML

XML Resources provide full functionality for reading and writing XML documents. The XML document structure can either be imported from an existing XML schema or can be created manually using the resource. Each resource can be configured with a number of adapters that control what is done with the XML documents e.g. read and write to/from file, read and write to/from a URL etc.

(See Working with XML for more information)

Web Services

Web Service Resources provide the ability to call a Web Service and receive a response. A Web Service Resource is very similar to an XML Resource. In addition, it allows WSDL files to be imported, and provides a Web Services adapter to call the web service i.e. send a request document and receive a response document. Web Services can also be published from Ebase using the Ebase Integration Server module.

(See Working with XML for more information)

MQSeries

MQSeries is a software product from IBM and that facilitates connection between applications by the reading and writing of messages to and from message queues. Ebase supports two types of operation with MQSeries:

· Writing a message to a queue. In this scenario, an Ebase form collects and validates information from the end user, and then transmits it to a 3^rd party system via MQSeries. This interaction can be either synchronous or asynchronous.

· Writing a message to a queue and then reading a response message. This interaction is synchronous and can be used to connect to a 3^rd party system as an integral part of form processing e.g. for a credit check.

(See Working with MQSeries for more information)

Printing

Ebase includes a fully flexible print form designer. This allows any number of multi-page print forms to be designed and associated with any given web form. When the user clicks a print button, the corresponding print form is displayed as a PDF and populated with any data entered by the user. The PDF document can also be saved on the server if required, or attached to an email. The print form editor supports a number of advanced features including:

Support for master pages
Support for styles i.e. colours, fonts, sizes etc
Inclusion of bar codes
Inclusion of images
Inclusion of rectangles and lines
Dynamically expanding elements

In addition, existing PDF form documents can be imported into print resources.

Migration

All Ebase element types may be migrated (copied) from one Ebase environment to another Ebase environment. This facility is primarily used for migrating a form and associated elements between development, test and production environments, although it may also be used to restore an earlier version of any element.

Migration is a 2 step process: export desired elements from source environment, import desired elements into the destination environment.

Exported elements are stored as XML, in a user nominated file, within a configurable directory. When exporting a form, a user has the option of exporting all related elements at the same time.

The import process allows all elements or a subset of the elements contained within an export file to be imported. Existing elements, if any, are overwritten by an import.