Appboard/2.4/builder/data sources/file

File based data adapters allow AppBoard to consume data from any files the server process has permissions to read, including network mounted filesystems.

The Shell Command adapter is a special case where AppBoard actually executes the specified command and then captures the response.

CSV File & Directory

Comma Separated Values (CSV) files are a common way to store tables of information and can be produced by a wide variety of applications and tools. The CSV File and Directory adapters allows AppBoard to consume data from these files including variations on these such as space and tab separated values.

Unlike other data adapters there is no specific caching options with the CSV adapters. Instead AppBoard will read and cache the response until next requested when it will check to see if the file has changed, if not then the cached copy is returned otherwise the file is re-read and the new data returned.

Configuration Options

Option	Description
Directory	Only applicable to the CSV Directory data adapter and defines the path containing the files to be read. See Specifying Files/Directories below for more information.
File Extension	Only applicable to the CSV Directory data adapter and defines the set of files AppBoard will look for in the defined directory, e.g. *.csv
File Path	Only applicable to the CSV File data adapter and defines the specific path and filename of the file to be read. See Specifying Files/Directories below for more information.
Data Delimiter	Defines the field separator which is comma by default, but can be set to semi-colons, spaces, or tabs.
Contains Header Line	Defines whether the file contains a header line, which should be the first row in the file. If no header is present the first row will also be used to define the field names.
Header Meta Delimiter	See below for a further information on header meta data. This option specifies the meta delimiter used for each field to separate the actual field name from meta information. By default this is disabled but can be set to asterisk (*) or hash (#)
String Boundaries	For files that contain strings which could potentially include the data delimiter character the fields need to be further grouped by quotes so the parser doesn't incorrectly split the field. Typically this should be set to Delimited by Quotes even in the case quotes aren't used as this still behaves as expected. Setting this to Not Delimited will specifically ignore quotes and split on every data delimiter found.

Header Meta Data

While it's simple to incorporate CSV data into AppBoard using the CSV data adapters, CSV files themselves do not define the data types of the columns. While this may be inferred AppBoard does not attempt to do this and the administrator needs to configure the types appropriately on the Explore step of the Data Source Wizard.

Starting with AppBoard 2.4 meta information describing the column types and primary keys can be encoded into the header line, removing the need to manually set the types and keys.

A Header Meta Delimiter must be configured for AppBoard to separate out the actual field name from the meta information, for example using an asterisk meta delimiter, and a comma data delimiter:

Name*STRING*PK,Description*STRING,Total*NUMBER,LastUpdate*DATE*yyyy-MM-dd

ExampleRow,Description Here,123,2013-06-24

The data types are the same as within AppBoard; BOOLEAN, NUMBER, LONG, INT, STRING, and DATE. In addition to the type, one or more fields can set the PK flag to indicate that particular field is a primary key. The DATE type also allows for the source date formatting to be defined using the same notation as within AppBoard

XLS File & Directory

The XLS data adapters are similar to the CSV adapters except they support reading from Microsoft Excel files.

Configuration Options

Option	Description
Directory	Only applicable to the XLS Directory data adapter and defines the path containing the files to be read. All files within this directory with the extention .xls are used. See Specifying Files/Directories below for more information.
File Path	Only applicable to the XLS File data adapter and defines the specific path and filename of the file to be read. See Specifying Files/Directories below for more information.
Sheet Name Regex	A regular expression to determine which sheet(s) to use from the XLS file(s). Each sheet will represent a separate entity.
Contains Header Line	Defines whether the a header row is present, which should be the first row in the file. If no header is present the first row will also be used to define the field names.

Shell Command

Typical usage for the Shell Command data adapter is to provide a generic integration method to AppBoard in cases where a more specific data adapter isn't appropriate. This adapter allows AppBoard to execute a command and capture the response which is expected to be in CSV format. As a result this adapter shares the CSV specific configuration options including support for header meta data - please refer to the CSV documentation above for more information.

Both static and dynamic variables (query SHIMs) can be provided to the script via command line parameters and setting environment variables. The combination of dynamic variables and CSV responses with meta information allows for tight integration with AppBoard.

Using the Shell Command data adapter means AppBoard will be spawning processes each time the data source needs to be queried. It's important to set reasonable cache timeouts to avoid excessive calls and factor in the additional load on the AppBoard server.

Configuration Options

Option	Description
Script	Defines the command to execute. See Specifying Files/Directories below for more information, however the default directory is [INSTALL_HOME]/server/webapps/enportal/WEB-INF/shell-script
Command Line Parameters
Handle Standard Error (stderr)
Environment Variables
Inherit Server Environment
Cache Timeout

Specifying Files/Directories

For all the adapters above when specifying the file path or directory a text input is shown with a purple magnifying glass next to it. By default the path shown is ${application.home}/data which is the equivalent of [INSTALL_HOME]/server/webapps/enportal/WEB-INF/data.

To have data files automatically included with full archives then place them under the [INSTALL_HOME]/server/webapps/enportal/WEB-INF/data/custom/ directory

The text input will accept any valid file path or directory as long as the AppBoard process has permissions to read it. For example, on Windows systems a valid entry could be C:\mydata\file.csv while on Linux and UNIX systems the following is valid /mydata/file.csv.

If the purple magnifying glass is clicked this will open the Remote File Browser dialog. Please note this browser is restricted to browse the [INSTALL_HOME]/server/webapps/enportal/WEB-INF/data directory only.

Remote File Browser