Specify Development Howto

From Filtered Push Wiki
Jump to: navigation, search

The Specify web app is written in Python and JavaScript. It provides a subset of the functionality of the Specify Java thick client.


To develop the web app, you will need an existing Specify MySQL database that was created with a certain schema version number and software version number, and has been populated with some system data (and preferably some specimen, taxon, and geography data as well). There are three options:

From a MySQL dump

I have created a dump that you can use that contains both system data and some fairly extensive taxon and geography data and one fake occurrence record. If you use this you might have problems matching the version numbers later on, but there are ways of handling that.

From the Specify Installer

Another approach is to download a Specify installer and run it, and choose the option to also run the Database Setup Wizard. The wizard will load geography data (and that takes a while), and you can opt in or out of having it load taxon data, but you won't get specimen data. Obtain the installer here:


under the heading "Specify (Full version)." The IT user/password you will be prompted for is for the MySQL root user account. The admin user/password will be used by the Specify application to control access to itself. Take note of the values you use for this.

Run the Setup Wizard from Sources in Eclipse

Another approach is to download the Specify source and run the main method from the class that runs the Database Setup Wizard. Some strategic edits to the source let you bypass the geography load. Other strategic file configurations will let you skip entering data by hand in the setup wizard screens. You can check out code at a revision corresponding to a release by consulting the table at the bottom of this page:


and going to Specify's SourceForge account to get the code:

> svn checkout http://svn.code.sf.net/p/specify/code/trunk/Specify

Once you have the code, import it into an Eclipse project, and then follow the instructions here:


to set up a project for it in Eclipse. Alternately, use Eclipse to check out the project (and then follow those instructions).

The main class you will run to build the database is edu.ku.brc.specify.config.init.SpecifyDBSetupWizardFrame. Set your working directory in the Eclipse launch configuration to be ${workspace_loc:ProjectName}/Specify or whatever directory path necessary to indicate the directory checked out with the above svn command; it is the one that contains src/ and config/. It may appear to hang, but you can always log in to MySQL as root and do

mysql> show full processlist

to see if anything is actually happening. I suggest creating/editing the file ~/Specify/user.properties to add an entry like this:


so that you don't have to manually enter data on the wizard screens, you just have to click through them. (You will have to either edit SpecifyDBSetupWizard to change the default root database password, or make the manual edit on the first wizard screen.)

Specify Working Directory

You will also need a directory that contains the jar artifact specify.jar and the config directory that comes with Specify installations.

From a tarball

You could unpack a tarball I've provided with a master directory that contains a suitable jar and config dir.

From the Specify Installer

If you downloaded and ran the Specify installer, the directory will probably be ~/Specify; otherwise, it will be somewhere different if you told the installer to put Specify somewhere else. In any case, the directory you want is named Specify and contains both specify.jar and another directory named config.

Specify Sources in Eclipse

If you checked out the code into an Eclipse project, the directory will be the immediate parent of config in your checked-out project.

Matching Specify Schema and Software Version Numbers

Once you have Specify code or binaries installed somewhere, you can see the app version number at the top of resources_en.properties. If you have binaries, this file is in the root of specify.jar. If you have source, it is in Specify/src/. The software version number looks like this:


You can override this by creating the file ~/i4jparams.conf containing a different version number, like this:

    <variable name="sys.version" value="6.5.02"/>

You can view the schema and software versions as recorded in the database with this select:

mysql> select AppVersion, SchemaVersion from spversion;

Running the Specify Client

If you are running from Eclipse, the main method is in edu.ku.brc.specify.Specify. If you have binaries, they are in ~/Specify/bin.

Web App

Get Specify's web app code and quick start instructions from here:


and get an overview here:


The Data Entry Tool

See the README.txt in http://svn.code.sf.net/p/filteredpush/svn/trunk/FP-DataEntry

Getting a Plugin into the SpecifyWeb App

1. Edit the xml view forms in the specify jar (depends on the form, but usually config/botany/manager/botany.views.xml) to add a cell like this in the view with name="CollectingEventSub". This is the form displayed for CollectionObject record sets. It is not displayed until the "Collecting Information" heading is expanded.

  <cell type="field" uitype="plugin" name="this" initialize="name=FindDuplicates"/>

2. Create a file containing the js code for your plugin. The name will be significant. Put it in specifyweb/frontend/static/js/.

  ... return UIPlugin.extend({
       __name__: "FindDupPlugin", ...

3. Edit specifyweb/frontend/static/js/specifyplugins.js to add the base name of your file ("finddupplugin") and the name of your class ("FindDupPlugin"), to the "namespace" declaration, and add an entry to the returned object that will correlate the name in the xml view form ("FindDuplicates") to the class ("FindDupPlugin").

                   <cell type="label" label="Find Duplicates" />
                   <cell type="field" uitype="plugin" name="this" initialize="name=FindDuplicates"/>

4. Add a template file and an entry in specifyweb/frontend/static/js/templates.js for the iframe html (see the geolocate plugin) so that the call to templates.finddup({'url': url}) will be defined and have content to load.