WIST (Workflow Information Storage Toolkit)
Version 1.1

SUMMARY
=======

WIST is a template-based toolkit to facilitate rapid LIMS (Laboratory
Information Management System) development.  WIST is designed to
create LIMS modules with a web-based front end and a SQL database back
end, along with a repository for larger data objects (e.g., files)
that are impractical to store in SQL tables.  WIST was developed by
the Protein Complex Analysis Project (PCAP), part of the Virtual
Institute for Microbial Stress and Survival (VIMSS).


HOW WIST IS USED
================

In developing a new LIMS module corresponding to an experimental
workflow, developers first design schema that are appropriate for
capturing the necessary data and metadata corresponding to the
experiments.  The LIMS developers may then use the WIST Builder tool
to analyze the SQL schema and create a corresponding template.  These
templates, which are text files that can be customized using an
editor, describe the workflow and allow WIST to provide a consistent,
unified, web-based interface for uploading, browsing, and editing
data.

Users upload data through the WIST Upload tool, which enables data
entry using a web form that may include a variety of component
widgets.  These widgets are described in the template, and customized
by the developers to correspond to various data types in the schema.
For example, to enter a date, either a pop-up calendar widget or a
text box may be used.  Other widget types include drop-down menus,
checkboxes, radio buttons, file upload boxes, and various text entry
fields.  Several of these widgets support multiple inputs; e.g., the
multi-file upload allows users to upload a fixed or variable number of
files, within a range specified by the developers.  All widgets
include AJAX functionality, which allows data input into one widget to
immediately change the values or number of inputs in another widget,
based on a function and/or database query.  Data entry may be
validated (e.g., allowing only a range of values, or preventing
floating point numbers from being entered as an integer data type);
invalid data entry results in a customized, user-friendly pop-up box,
and the problematic field being visually highlighted.  The data entry
forms may include multiple steps and branches (specified in the
template) before data is finally committed to the database.  WIST
Upload was recently enhanced to include parsed data upload, a feature
that allows users to upload a file (e.g., spreadsheet or text file)
corresponding to multiple rows in the database; this feature is
especially useful for high throughput data entry.

Once data is uploaded, it may be viewed in the WIST Browser.  This
web-based tool supports additive filtering, searching, pagination, and
column-based sorting (ascending and descending sorts are supported).
The type of view is described in the URL, a feature that allows LIMS
developers to create hyperlinks corresponding to frequently used
searches and views.  The WIST Viewer allows users to see all details
of individual entries.  Finally, the WIST Editor allows users (if
enabled by the developers) to edit data using an interface that is
nearly identical to the WIST Upload tool.  The various WIST tools are
tightly integrated using hyperlinks, so users can move between them
seamlessly.


MAILING LIST
============

The "vimss-wist" list is for discussion among developers and users
of the code.  If there is sufficient demand, we can split off other
lists.  The mailing list is hosted on SourceForge:
  http://lists.sourceforge.net/mailman/listinfo/vimss-wist


REQUIREMENTS
============

Web server: Apache 2.0+
Database: Mysql 4.1+ or PostgreSQL (tested with 9.0.1)
Utilities:
* Perl 5+ (tested against 5.8.7 and 5.8.8)
* memcached
* cURL

Extra Perl modules required (CPAN package names given below)
* Cache::Memcached
* Bundle::LWP
* MIME::Types
* POSIX::strptime
* DBI
* DBIx::Class
* DBIx::Class::Schema
* DBD::mysql (only for Mysql)
* DBD::Pg (only for PostgreSQL)
* GD
* GD::Thumbnail

More required Perl Modules (should already be available in Perl 5, or
automatically installed as dependencies with the above, but may be
missing in very early Perl 5 distributions):
* Perl 5 IO
* CGI
* Data::Dumper
* Getopt::Long


INSTALLATION
============

See INSTALL.txt


SUBVERSION REPOSITORY
=====================

There is now a public Subversion repository for the project, hosted
by Sourceforge.  You can browse changes to the code here:
  http://vimss.svn.sourceforge.net/viewvc/vimss/

To check out the very latest (possibly broken) version of the code,
install Subversion and do:
  svn co https://vimss.svn.sourceforge.net/svnroot/vimss/trunk


REFERENCE
=========

If you publish research in which you used WIST, please cite:
(citation pending).