Configuring the framework for your project

Most project configuration occurs in the commonConfiguration.properties file. This file is located in the following location in your Shepherd Project installation:

<install_directory>/WEB-INF/classes/bundles/commonConfiguration.properties

When you modify configuration parameters in this file, you may have to restart your J2EE container (e.g., Tomcat) for the changes to take effect.

The Shepherd Project uses on DataNucleus Access Platform, which allows it to use a number of different databases and database types. DataNucleus "persistence properties" control the database used by the Shepherd Project and are defined in the file jdoconfig.properties. By default, the Shepherd Project is configured to use an Apache Derby database, which is excellent for demonstration purposes. However, for Web-scale application, or if you intend to manipulate the database tables externally, other relational databases (e.g., PostgreSQL or MySQL) are recommended. Depending on the database software you choose, you may need to manually create the database and define a username and password for it. When provided with these credentials, the Shepherd Project can automatically create the necessary tables and columns when it is first started. You do not need to create these yourself.

An example of DataNucleus persistence properties is shown below.

#DataNucleus parameters for object persistence

# the following two lines create a connection to an embedded derby database.
datanucleus.ConnectionDriverName=org.apache.derby.jdbc.EmbeddedDriver
datanucleus.ConnectionURL=jdbc:derby:shepherd_derby_database;create=true

# the following three lines create a connection to a MySQL instances
#datanucleus.ConnectionDriverName=com.mysql.jdbc.Driver
#datanucleus.ConnectionURL=jdbc:mysql://localhost:3306/shepherd

#the following lines can be used for PostgreSQL persistence
#datanucleus.ConnectionDriverName=org.postgresql.Driver
#datanucleus.ConnectionURL = jdbc:postgresql://localhost:5432/myDatabaseName

javax.jdo.PersistenceManagerFactoryClass=org.datanucleus.jdo.JDOPersistenceManagerFactory
datanucleus.ConnectionUserName=shepherd
datanucleus.ConnectionPassword=shepherd
datanucleus.autoCreateSchema=true
datanucleus.NontransactionalRead=true
datanucleus.Multithreaded=true
datanucleus.RestoreValues=true
datanucleus.storeManagerType=rdbms

You can control the Shepherd Project's database behavior by changing the values of these properties and by adding others, as defined in the DataNucleus persistence properties documentation. Any properties in that file that start with “datanucleus” or “javax.jdo” influence where and how data is pulled by the Shepherd object.

The example above includes some commented out values for PostgreSQL and MySQL databases. These values are ignored because they are prefaced with the # character.

Note: You will also have to import the JDBC driver JAR file for your chosen database type and add it to the <install_directory>/WEB-INF/lib directory. Your J2EE container (e.g., Tomcat, JBoss, Jetty) will also need to be restarted to pick up changes in this properties file.

The HTML header for web pages in the Shepherd Project is pulled from the file header.jsp. This file retrieves additional values from commonConfiguration.properties.

The file header.jsp contains the following code, which retrieves the graphic displayed at the top of each page in the Shepherd Project.

<div id="header">
<img name="masthead"
           src="http://<%=CommonConfiguration.getURLLocation(request) + "/"
           + CommonConfiguration.getURLToMastheadGraphic() %>" width="810"
           height="150" border="0" usemap="#m_masthead" alt=""/>
</div>

The following code shows the line in the header.properties file that specifies which graphic to display.

#URL to the graphic to be displayed at the top of every page through header.jsp</p>
urlToMastheadGraphic=images/masthead.jpg

All paths are relative to the Shepherd Project installation directory.

To change the top banner graphic, follow these steps:

1. Add your new header graphic to the images folder in the following location:
   

   [shepherd_home]/images
   

   The graphic can be any file format that displays in a browser, such as .jpg, .gif, or .png.
2. Edit commonConfiguration.properties.
3. Modify the urlToMastheadGraphic field to point to your new graphic.

#URL to the graphic to be displayed at the top of every page through header.jsp
urlToMastheadGraphic=images/myMastheadGraphic.jpg

4. Save commonConfiguration.properties.
5. Restart your J2EE container.

The Shepherd Project uses the ecocean.css cascading style sheet to control certain visual elements of the framework. If you want to substitute your own style sheet, modify the configuration parameter cssURLLocation.

cssURLLocation=css/ecocean.css

1. Add your new style sheet to the [Shepherd_Home]/css directory.
2. Edit commonConfiguration.properties.
3. Modify the cssURLLocation field to point to your new style sheet.

cssURLLocation=css/myStyles.css

4. Save commonConfiguration.properties.
5. Restart your J2EE container.

The Shepherd Project's default URL is

http://localhost:8080/[Shepherd_Release]

If you deploy the Shepherd Project to a named domain, you must change the project URL. The project URL is determined by the configuration parameter urlLocation. Follow these steps:

1. Edit commonConfiguration.properties.
2. Modify the urlLocation field to point to your internet domain.

#base url of the web site
urlLocation=JellyWorld.org/Shepherd

3. Save commonConfiguration.properties.
4. Restart your J2EE container (e.g., Tomcat).

If your mark-recapture project deploys the Shepherd Project to a custom, publicly accessible URL (e.g., www.whaleshark.org), you can request custom search keys from Google and place them in the following fields of commonConfiguration.properties.

#Google Service keys for Search
googleSearchKey=ABQIAAAAmb5-A-em_VabiiSEGZpvmRRTprTin5h_0-odPYUGB6h2YV9tQBSSk7LPXt9jxgaFm7Pt0GVfRimDdw

A Google Search key for your domain name can be requested from these links:

• Google Search key request form

By default, the Shepherd Project assumes that information added to the database is germane to only one species of animal. You can configure the Shepherd Project to support multiple species by setting the genusSpecies fields, and setting the showTaxonomy parameter to TRUE in commonConfiguration.properties. The following example shows how to set these properties to differentiate between three species of large cats.

#show taxonomy
showTaxonomy = true

#for multi-species libraries, fill out the genus and species for each supported animal type, starting with genusSpecies0
genusSpecies0=Lion
genusSpecies1=Tiger
genusSpecies2=Leopard

Once these fields are set, the Taxonomy field appears when you edit an encounter.

If you click Edit on the Taxonomy field, the panel displays a Reset Genus and Species field.

The following email addresses are sent messages when important events occur in the Shepherd Project. These email addresses are specific to your project.

1. sendEmailNotifications - Defines whether the Shepherd Project should send any emails at all. Set to true, this parameter instructs the Shepherd Project to send email updates for several events, such as:
   • new Encounter submission reports
   • new marked individual identifications to adopters ad submitters
   • marked individual resights to adopted and submitters
2. autoEmailAddress - The email address from which Shepherd Project messages will be sent. If you have a secured mailhost, it's important to configure the mailhost to allow emails to be sent from this address.
3. newSubmissionEmail - The email address to send notices of new Encounter reports submitted to the Shepherd Project.
4. mailHost - The email server through which the Shepherd Project can send automated emails.
5. removeEmailString - This is the message that will be appended to outbound emails in the Shepherd Project. This message and the link that is dynamically attached to it allow users to stop receiving emails from the Shepherd Project.

#email addresses and parameters
sendEmailNotifications=true
autoEmailAddress=webmaster@someplace.org
newSubmissionEmail=submissions@someplace.org
mailHost=localhost
removeEmailString=Do you want to REMOVE your email address from this database? Click the link below to remove it. You will no longer receive updates on your encounters.

The isCatalogEditable option allows you to create a dynamic (true) or static (false) mark-recapture catalog. A dynamic catalog allows users who log in to add/remove/update data in the Shepherd Project. A static catalog represents a completed, unchanging set of mark-recapture data that is historical in nature, such as a fixed duration initiative.

#library editing
isCatalogEditable = true

TBD

#pattern recognition
useSpotPatternRecognition=true

#Modified Groth algorithm parameters for spot pattern recognition
R=8
epsilon=0.01 
sizelim=0.9
maxTriangleRotation=30
C=0.99

TBD

The following papers discuss the two spot pattern recognition algorithms available in the Shepherd Project. Understanding the two-dimensional limitations of these algorithms and adopting appropriate data collection and processing procedures are critical to their successful use.

• Arzoumanian Z, Holmberg J and Norman B (2005) An astronomical pattern-matching algorithm for computer-aided identification of whale sharks Rhincodon typus. Journal of Applied Ecology 42, 999-1011.
• VAN TIENHOVEN AM, DEN HARTOG JE, REIJNS RA and PEDDEMORS VM (2007) A computer-aided program for pattern-matching of natural marks on the spotted raggedtooth shark Carcharias taurus. JOURNAL OF APPLIED ECOLOGY 44, 273–280.

When you deploy the Shepherd Project to a web server for use by researchers on the internet, you can set the wikiLocation parameter to the URL of an integrated wiki on your site. The wiki can act as an information delivery engine for detailed instructions specific to your application, or a place to add details about your organization's mission and goals, or for any other information you feel your customers need to know.

To set the wiki location, follow these steps:

1. Edit commonConfiguration.properties.
2. Modify the wikiLocation field to point to your internet domain.

# set wikiLocation to point to your wiki to enable integration, e.g.
wikiLocation=http://myWebSiteDomain:8080/wiki/doku.php?id=

3. Save commonConfiguration.properties.
4. Restart your J2EE container.

The following configuration options allow you to export data to popular biodiversity data frameworks.

TAPIR is the Taxonomic Databases Working Group (TDWG) Access Protocol for Information Retrieval. A complete description of TAPIR is here:

http://www.tdwg.org/activities/tapir/

This Shepherd Project feature allows you to install a TapirLink provider (a third party application for biodiversity data sharing using TAPIR) and share your Shepherd Project database information with the Global Biodiversity Information Facility (GBIF) and other databases using TAPIR.

To enable this feature, follow these steps:

1. Download a TAPIR Link Provider from the following location.

   Tapir Link Provider

2. Follow the provider instructions to build a servlet containing the TAPIR Link provider.
3. Use the tapirLinkURL property in commonConfiguration.properties to set the launch URL for the provider.

   #TapirLink-related settings tapirLinkURL = http://localhost:8080/tapirlink/admin/configurator.php

4. Follow the provider instructions to expose the Encounter Table data in the Shepherd Database to TDWG.

When the tapirLinkURL property is set, the Administer menu displays a TapirLink menu item. To launch your TapirLink provider from the Shepherd Project, choose Administer → TapirLink.

The Global Biodiversity Information Facility (GBIF) was established by governments in 2001 to encourage free and open access to biodiversity data across the Internet. The Shepherd Project allows you to share data with GBIF. Complete information on GBIF is here:

http://www.gbif.org/

The IPT provider (Integrated Publishing Toolkit) is a Java web application (delivered as a WAR file) that allows you to directly expose biodiversity data in a relational database to an external parser at the GBIF. The GBIF periodically collects the data and incorporates it into a larger biodiversity database.

The Shepherd Project allows you to specify a link to the IPT that corresponds to your Shepherd Project instance and display that in the Administration menu. The user has to consult the IPT documentation for instructions on how to map IPT into the Shepherd Project database (specifically to the Encounter table). It's the same process for TapirLink as well.

To integrate the Shepherd Project with IPT, follow these steps:

1. Download The Integrated Publishing Toolkit from the following location.

   IPT Provider

2. Follow the provider instructions to build a servlet containing the IPT provider.
3. Use the iptURL property in commonConfiguration.properties to set the launch URL for the provider.

   #GBIF IPT-related settings
   iptURL = http://localhost:8080/ipt-2.0.2
   

4. Follow the provider instructions to expose the Encounter Table data in the Shepherd Database to GBIF.

When the iptURL property is set, the Administer menu displays a GBIF IPT menu item. To launch the IPT provider from the Shepherd Project, choose Administer → GBIF IPT.

TBD

TBD

TBD

You can configure many attributes of Encounters.

Encounters can be assigned to particular states, often reflecting part of a project workflow. The available states are defined in the following section of commonConfiguration.properties.

#encounterState options, the precursors to future workflow
encounterState0=unapproved
encounterState1=approved
encounterState2=unidentifiable

You can configure reported encounters to have n-number of recorded measurement observations (e.g., length, width, height). The measurement types are defined in commonConfiguration.properties, starting with the number 0 and incrementing by one for each new measurement type.

For each measurement, you must define a measurement name, the corresponding units, and the general sampling protocols applied to measurements in your study. You can turn and off measurements altogether with the showMeasurements entry, which can be set to true or false.

#show measurements
showMeasurements = true

#Measurements
measurement0=weight
measurement1=length
measurement2=height

measurementUnits0=kilograms
measurementUnits1=meters
measurementUnits2=meters

#Sampling Protocol for Measurements
samplingProtocol0=estimate
samplingProtocol1=measure

TBD

#show lifeStage
showLifestage = true

#defined life stages
lifeStage0=juvenile
lifeStage1=sub-adult
lifeStage2=adult

TBD

#limit Encounter.locationID to these values
#locationID0 = location0
#locationID1 = location 1

TBD

#tag parameters
showMetalTags=true
metalTagLocation0=left
metalTagLocation1=right

showAcousticTag=true

showSatelliteTag=true
satelliteTagName0=Wild Life Computers
satelliteTagName1=SirTack

TBD

Manual: