by Markus Döring , m.doering@bgbm.org
and Javier de la Torre j.torre@bgbm.org
Botanic Garden and Botanical Museum Berlin Dahlem
22 Juli 2004
Based on NoDIT v 2.0 RC4
http://www.biocase.org/Nodes/nodit/documentation.shtml
Welcome to the NoDIT documentation. In the next chapters you will learn how to get, install, use the new NoDIT v 2.0.
The new version of the software has many advantages in the usability of the tool and the internationalization of several fields. We hope you like it and we are always open for feedback and suggestions, please do not hesitate to contact us.
This document is divided in three big chapters: Introduction, installation and using NoDIT. In the second you will learn how to make everything run and in the third one how to use the new Access interface.
The NoDIT software has two parts. One is the Access database with the NoDIT application that runs on it and the other is the necessary software to allow the central BioCASE server to collect the data from every node.
In this update of the NoDIT software this second part has been widely changed and that is the reason why you will have to configure again your web server.
We hope you do not find any problem while configuring the software and please contact us if you experience any problem.
The installation process basically will be:
All the following explanations will assume that the machine where you are going to install the software is a Windows machine. If you want to run it in a Unix environment please contact us for support.
The first thing you will have to do, if you haven't done it already, is to download the new Access database from the BioCASE website. Go to the next URL:
http://www.biocase.org/Nodes/nodit/downloads/
And download it. (is the first link)
Uncompress the database into the same folder where the old NoDIT was, for example. You can also save it in another location if you want. For uncompressing the database you can use any ZIP decompression program.
Give all users and processes (user 'Everyone' on NT and W2K) the rights to read the file. This is essential for setting up a working ODBC system datasource, accessible by the wrapper.
Right click in the database file-> Properties -> Security (check the image)
Open the nodit2.mdb file that you have just uncompressed. You will notice that the new NoDIT interface is very similar to the old one. In chapter 3 sou will learn how to use tab by tab all functions that the program includes. Now we will only import the data from the old NoDIT version.
First introduce your name in the application. Then go to the "Import/Export" tab. You will see three buttons. For importing from the old NoDIT click the second one. You will see:
Click on "select a database" and browse to the location where your old NoDIT database with the data that you want to import is and select it. Click on Import data.
The process can take some time depending on how many records you had in your old database. You will get a message when the process is finished.
Check that if you have introduced some data in this new database and then you import data from and old database all data that you entered will be overwritten. Because you haven't started using the new database you do not have to worry about.
When finished you will have all your old data in the new database structure.
Close the Access program for the moment and w continue with the installation process.
If you were allready using the old NoDIT you will have allready a DSN connection configured in your database, if not you will have to create a new one. A DSN connection is used to specify which database will be published.
To modify the existing one or to create a new one go to Control Panel and then click on Administrative tools (for Windows 2000, XP and 2003), then click on "Data Sources (ODBC)". If you can not find it just run "odbcad32.exe" at the ODBC Data Source Administrator should be launched. Check your Operating system help if you don't manage to find this.
Click on the "System DSN" tab. You should find a Sytem data source
called "nodit" in the list. Click on it and press
"configure". Then in the next screen click on "Select", then
browse to the place where you have stored the Nodit 2 database. Accept all the
screen when you have finished.
If you didn't have the "nodit" data source you will
have to create it, the process is very similar, the only difference is that at
the beggining you will have to select "Access driver" from the list of
available drivers.
Notice that the DSN (Data Source Name) should be "nodit" or the software will not work.
Go to:
http://www.biocase.org/Nodes/nodit/downloads/
and download the "ProviderSoftware 1.4 for NoDIT v2".
Save it somewhere else provisionally. When you decompress it you will find that there is a biocase folder on it. You will have to publish this folder with your Web server.
In this document we assume that you either are experienced with setting up a webserver, or that there is technical staff around who can help you. The following description will focus on the BioCASE specific tasks. If you will have to install a webserver for the first time in your local network, you will also have to take care of firewalls and how to provide public access from the Internet to your webserver. If you are not familiar with this, please contact your IT staff or someone else with technical knowledge. As a webserver is meant to provide public data to other people, there is a risk of creating security holes for your network or personal computer.
When you have your Webserver up and running you will have to create a public folder where the BioCASE software will be installed. We will call this folder the biocase folder. If you are upgrading your old database then you can replace the PHP files of the previous NoDIT version with this folder and forget about the next steps.
The process of creating a public folder is much dependent upon your operating system, the kind of webserver and how is it installed. In short, we can say that there are two possibilities to do so:
Create a folder called biocase inside your www root folder.
Create a so called Virtual Directory somewhere else with the biocase name.
It doesn't matter which way you do it. The important thing is that at the end you will have created a public folder that could be accessed from the internet, for example, in this way:
http://www.yourserver.org/path_where_you_want/biocase/
The location that we will use in this documentation will be http://www.yourserver.org/biocase/ and locally in the server C:\Inetpub\wwwroot\biocase
But you could also install it in D:\DataProvider\Biocase and have a url like http://yourserver.org/ABCDproviders/Biocase/. It's up to you.
The new NoDIT software uses Python for the process of exporting your data to the central CORM database. That is why you will have to install Python and configure it for your web server.
First of all, you will have to download the Python program. Go to http://www.python.org/download/ and download the latest version of Python available for your operating system. At the time of writing, the latest version of Python is "2.3.2" and the BioCASE software is known to work correctly with that version. When you have finished downloading Python you have to install it.
In Windows you will just use the windows installer that is very easy, follow our explanation below. For Unix please read the installation instructions. We recommend that in Windows you install Python in the proposed location, as you might have to modify some BioCASE scripts. In all the provider software scripts for win32 it is assumed the Python interpreter is found at C:\ Python23\python.exe If this is not the case, you will have to modify the first line of every cgi script.
Click on next, then, if it asks you for backups of your files, select yes (if it's the first time you install Python, it will not ask you). Then click on next and you will get to the "Select Components" screen. There you can find a button called "Advance Options". Click on it and you will see a screen like:
Select the Non-Admin install. This is because in old Windows OS (like NT 4.0) selecting the Admin install option can make the system to crash.
Then click Ok in this screen and in all the following ones. The Python installation should run without problems.
In order to use Python as a scripting language for CGIs, you have to tell your webserver where to find your Python installation and how to identify a Python CGI script. The procedure to do so is very much dependent on the kind of webserver that you are using.
Follow this step by step procedure (original version: http://www.urbanware.com/python/pythonIIS.html). The screenshots are taken from Windows 2000 but Windows XP is almost the same.
Then fill the window that looks like this one (change the path to Python.exe if you have installed Python in another location). Make sure you include the “%s %s” parameters.
If you have an already existing installation of Apache, ask the IT responsible person for help. In case you have a fresh installation, it should be sufficient to add the following lines of code to the end of the httpd.conf configuration file in your Apache installation:
AddHandler cgi-script .py <Directory "C:/Program Files/Apache Group/ Apache2/htdocs/biocase/"> Order Deny,Allow Allow from all Options +ExecCGI AllowOverride All </Directory>
Adjust the path C:/Program Files/Apache Group/ Apache2/htdocs/biocase/ to point your provider software folder (see 3.2). You need this to allow Apache to execute CGIs in your wrapper instance folder.
Remember to restart Apache so that the changes take place.
If you choose to use Apache under Windows and in Unix installations, you might have to modify the Python scripts a little. All Python scripts were written for a standard Python 2.3 installation on Windows NT/2000. If you installed Python in another location than this #!C:/Python23/python.exe, please update the first line of every script you are using (dbwrapper.py, CGItest scripts) so that it refers to your Python executable. For Unix by default the cgis will be lunched from /usr/bin/env
Now you will test your Python installation and install other software that is needed. This process will be done using a web page that you should have already published, if all the installation and configuration processes have been successful. Go to the next location:
http://localhost/biocase/cgi-test/index.html
This location may change if you have configured your BioCASE public folder in another location, you have defined this in section 3.1.
You will see the next web page:
If you cannot access this page, you will have to check all the steps that you made before. This page only uses HTML. If you cannot see it you are probably accessing an incorrect url or your webserver is not properly configured. If you have re-checked everything and you cannot find the solution, contact us at support@biocase.org.
To continue with the installation process, click on the first link, Test your Python CGI installation. If the result is a "Hello World message" this will mean that you have installed Python correctly on your server and that you have configured the webserver to run cgis, congratulations!. If not you will have to check the configuration again, or contact us.
If everything is ok, you can continue with the installation process.
On the same page as before please click on the second part of the test. You will see a web page like this:
On this page you can find the libraries needed for running the BioCASE wrapper software. You have to download and install each library one by one. These libraries extend your Python installation.
PyXML: A library needed for working with XML files. Click on the link to go to the official web page of this package and download it. In the download section you will find different versions of the library for different operating systems and Python installations. Choose the correct one for you. For Windows and Python 2.3 currently the file is PyXML-0.8.3.win32-py2.3.exe The installation process depends on your operating system. For Windows just download it and execute the file, it will do everything for you. By default you will see that this library is already installed with a version 1.0.x, this is a experimental version and you need to install the one that you will find following the link that is provided.
mxDateTime: The process for installing this library is very similar to the previous one. Just download and install it.
PyWrapper: This is the main library needed for running the wrapper. Click on the link, and in the Downloads section of the page that is opened select the file for your operating system. While this document was written the file for windows was PyWrapper-1.2.win32.zip. Install it the same way as the other libraries that you have installed before.
mxODBC: This library is needed to access databases using ODBC, please install it also in the same way.
When you have finished installing all this libraries return to the Python Library Tests were you started and refresh the page. You should see now that you have all the libraries needed installed already and which version they are. The next image shows what you should see, just the version numbers might be different, but that's ok.
If everything has been ok so far. you have almost finished installing the NoDIT v 2.0 software.
But first try the last test step. Go back to the previous page and click on the Part 3 test. Check if it's ok, if not please send us an email with the error message that you get. It is very unusual that the installation should fail at this point.
The installation of the new NoDIT version is done. Now you should send the url of your wrapper to the BioCASE secretariat (secretariat@biocase.org) and also to support@biocase.org
The URL will looks like:
http://www.yourserver.org/biocase/databases/NoDIT2/dbwrapper.py
In the following chapters we will explain the use of the NoDIT software.
NoDIT is an Access application, that means that you need to have Microsoft Access installed in your computer to be able to run it.
Open the file and you will see something like this:
If you get an error when opening the file please check the FAQ (Frequently Asked Questions) page or contact us for support.
When you open the application the first thing that you will have to do is to insert your name.
You can see that there is a common menu on the left part always visible and some tags that display different forms for entering data.
A the botton of the application you can find a control menu to move trough the records that there are allready in your database. In the image you can see, for example, that we are in the record number 6 that corresponds to the "Botanic garden & Botanical Museum Berlin-Dahlem".
NoDIT is used to enter metadata belonging to three categories or type of objects. They are used to represent the hierarchical structure of how collections are organized:
- Network:
Metadata about a network of organisations.
This is the highest level category, but networks can be part of other networks.
- Organisation:
Metadata about an organisation holding collections.
This is the intermediate level. The actual information about individual
collections is given by one or several "collection" level entries
which form part of the organisation. Some keywords may already apply to this
level.
- Collection:
Metadata about collections.
Here belong all specific data known about a collection.
A collection can be part of another collection to reflect individually described
subcollections.
We will see how to create them later.
When you've got the NoDIT open you are already woking in one record, in the main tab you can see the name and the basic information. When open the NoDIT always show you the first record that was inserted in the database.
To move forward or backward in the database trough all the records you can use the control buttons that are situated at the botton on the form.
Click on the bottons to move one by one or to end or begining of the database. You can see also the total amount of records that are allready in the database.
Other way of naviate trough the different records is searching for an specific record.
Use the
searching facilities in the left menu to find a specific record. This search
function will search in the name of the unit. You can specify the type of unit
(organization, Collection or Network) in the list. When you search for something
NoDIT will move to the next record that match your result, if you cick again it
will move to the next one until you get a message that there's no more records
matching your search.
Notice that you have to use wildcards (*) in your searchs, so if for example you want all records that have the word "plant" in their name you will have to search for "*plant*". If you want all records starting with "Botanic" you will have to insert "Botanic*".
On
the left menu you can see three different buttons for creaing one of the three
types of units that BioCASE defines. Click on one of them and you will see that
you have created a new record and that all the fields are empty.
For deleting a record, move trough the database until you are situated in the one you want to delete. Then click on delete record. You will be asked to confirm your action.
You can see always at the left menu a semaphore green or red indicating if a record is valid or not. Being valid means that all the mandatory fields for a record are filled, these are:
-Name of the record
-Description
-Institution name for the postal address
-Town where the org/coll or network is
-Country where is located
To check if a record is valid or not you can click the "check validity" button. If the record is not valid then you will get a message box indicating what information is missing and you will be redirected to the field automatically. You can see that mandatory fields got a red asterisk (*) near the name of the field.
Notice that only valid records will be then export to the CORM database and will be published in the BioCASE website.
The new NoDIT version has a lot of more new report funcionalities than the previous one. Click on the Report button on the left for accessing the report window.
Clicking on the different buttons will produce a different report. For exit this form click on the button on the upper right corner.
There are three types of reports basically. The first one will create reports
of all the records that are inside the database. There are different reports
depending in what information you want to include on it. The structure report
will create a document where you can see the relations of the different records.
Other type of report is the one covering only the selected record, that means
that the report will include only the information of the record that was
selected when you called the report window.
Finally the "controlled" report will show you a list of controlled
vocabulary words that can be used as keywords.
Now that we have described all the elements of the left menu of NoDIT we will explain the different tabs that you can find at the top of NoDIT.
The tabs change depending if you are editing a collection, a network or an organization because the information that you can fill for them is different.
Take a look on them. Remember that if you want context help for an specific field you can just leave the mouse pointer in front of it for two seconds and you will get a description of the field.
Now we will describe tab by tab all of them.
We will start with the main tab. This is the one that you always see first.
In this new version of NoDIT you can specify several names, descriptions and urls in different languages for a network, collection or organization.
Tha name of the body (org., oll. or netw.) is a little bit different to the other data. In the name you have to specify a prefered name, the one at the top of the form, then you can specify secondary names in different languages.
To add a new secondary name select the language of the new name and a new
window will appear where you can write the new name. You can doblw click on a
secondary name in the list to edit it. You can also select it and click on the
edit button (
) or
delete it with the delete button (
).
The process od adding, edit or delete descriptions and urls is the same.
Records could be part of another record or from multiple records. To add this relation you can "add parents" to your record. Select them from the list and they will appear on the list of parents for this specific record. Check that a network could be only part of another network, an organization could be part of a network of or another network and a collection from the three levels. So in the list of available bodies to select a parent only the possible ones will appear.
When you have select a parent for your record you can import all the data from it. That is useful when you don't want to type again the address information for example, you copy the content from the parent and then you modify slightly the data.
Finally at the bottom left part of this form you can see the information on whom was the last user that modified the record and when.
Purpose:If this network, organisation or collection has a special purpose it may be indicated here.
Access restrictions: Free text description of the conditions of access to the organisation or collection.
Strengh:If this network, organisation or collection has an
aspect in which it is particularly strong it can be highlighted here.
Free text, as compared with CollectionFocus, which may only contain specific
terms.
May include mention of one or two “star” items.
Usage restrictions:Free text description of what use of the collection is allowed, having gained access.
Citation: citacion for the record
Disclamair:Free text description of desclamair that the org./coll./netw. wants to define.
Notes:Place for any information that does not fit anywhere else.
In this tab you can specify the postal address information of this record.
Institution Name: The Name of the Institution for postal addresses.
Sub Unit Name: Name of the sub-unit(s) of the Institution.
Address lines: Repeatable holder for the more specific postal address details.
Zip: zip
Town: Name of town or city.
Region: County or Department or equivalent.
ISO Country: Country
Telephone: Full international telephone number.
Fax: Full international fax number.
Email: Expected to be an Internet email address as default.
Logo URL: URL of a graphic file that may be included with search results to give a visual indication of the source of the information.
Not complete!
Not complete!
Not complete!
Not complete!
Not complete!
Not complete!
Not complete!
The success of the BioCASe project is largely dependant on the quality of the data that it provides. The data must be structured in a way that is logical and easily understandable and there must be a uniformity characterizing the data content that is preserved across all data providers.
Nodit is a tool that can help you create the necessary structure for your data, but adherance to that structure and quality control of the data itself remains in the hands of you - the national nodes.
Please refer to the following guidelines when entering data in your national node metadatabase.
When you enter networks, organizations, and collections in Nodit (or your respective metadatabase) please try to capture the hierarchical structure involved, if it is present. For example, an organization generally houses several collections, and each collection may contain sub collections.
Nodit provides the means to represent these hierarchies. When you enter an organization in Nodit the Organization Specific tab allows you to specify the type of the organization and the number of collections it contains. When you enter a collection in Nodit the Add parent field on the Main tab allows you to attach it to an organization or an umbrella collection.
Some collections may stand independently while others belong to organizations or “container” collections. Avoid entering 'orphan' collections by including information about the organizations or parent collections that they belong to.
There may be differences of understanding that exist among national nodes regarding what is considered an organization and what is considered a collection. For example, one national node may enter a herbarium as an organization, while another may enter a herbarium as a collection. This lack of uniformity can be a source of confusion for users of the BioCASe system.
If you are entering a record that can be categorized as one of the following types, enter it as an organization. If you are entering a record that does not fall under one of the following categories, use your personal discretion about whether it should be entered as an organization or a collection.
Administration Association Aquarium Botanic Garden Field Station Herbarium Horticulture Independent Expert Laboratory Library Museum Government Bureau (Nature Education Center, Nature Reserves Management, etc) Non-Governmental Organization (NGO) Non University College Private Company Research Institute University Voluntary Observer Zoo
There may be confusion about organizations that are sometimes, in effect, standalone collections. For example, a small herbarium that doesn’t have any subdivisions could be considered a standalone collection, whereas a larger herbarium that houses several sub collection could be considered an organization.
In the interest of preserving uniformity, if you have a unit that falls under one of the organization categories above but can be considered a standalone collection, create an organization record for it, and then create a separate collection record and attach it to the parent organization record. For example, if you want to enter data for a small herbarium called “XXX Herbarium”, create an organization record for “XXX Herbarium” and then create a collection record called “XXX Herbarium Collection” and attach it to the organization parent. If the herbarium contains a number of collections then create a separate collection record for each one and attach them to the organization parent.
Curators must use their discretion when entering sub collections. For example, if a curator considers a family specialty to be large enough to be listed separately with a specific description and keywords, then that specialty can be entered as a separate collection record and then attached to the parent collection record.
Add the word “collection” to every collection name that you enter. For example, if you want to enter a record for a collection of paleontology then enter the collection name as “Paleontology Collection” rather than “Paleontology”.
Although BioCASe allows for the use of multiple languages, it is best to include English wherever possible so that your data will be widely understood. Use other languages only in addition to english!
When entering data in Nodit, hold your mouse over a field name in order to get a pop-up explanation about the type of data the field is meant to contain. Please refer to the following suggestions for more specific guidelines about how to enter data.
Free Text Descriptions
Description, Access restrictions, Usage restrictions, Purpose, Strength, Address, and Zip are examples of free text fields. The BioCASe indexing tool extracts meaningful terms from some of these fields in order to provide new terms for the thesaurus.
Avoid personal notes in free text fields such as "data still incomplete", "details to be entered later", or "unknown", since the indexing tool does not know how to resolve this type of entry.
Do not refer to URLs that are listed elsewhere by comments such as "for details see URL" since the indexing tool cannot resolve this type of entry. If you must include a URL that is listed elsewhere, cite the entire URL even if it creates redundancy. For example: "for details see http://www.bgbm.org".
You can fill certain free text fields, such as the Description field, by copying and pasting text from an organization website.
URLs
When citing a URL, either in specific URL fields such as Logo URL or Available URLs or in a free text field such as Description, list the full URL including the http://.
Keeping Data in Proper Fields
Keep data in their proper fields. Information about loans belongs in the field Usage restrictions, while information about opening hours belongs in the field Access restrictions. Keep town names in the Town field and region names in the Region field.
Do not combine data that belongs in two separate fields into a single field. Entries such as "Gloucester GL2 73X" in the Town field are inappropriate – use both the Town and the Zip fields.
Only use the Notes field when the data you are entering does not belong in one of the other fields available or if the data is too long to fit in the appropriate field. There is no need to list opening hours in the Notes field if they will fit in the Access restrictions field.
Keeping Data Appropriate
Make sure the data you enter is appropriate for the field you are entering it in.
Only use the field Collection code if the collection you are entering has a code associated with it. Do not simply repeat the collection name in the Collection code field. Note that more than one collection can have the same code since it is not a unique identifier.
Data that you enter in the fields Purpose and Strength should address areas in which a collection has a special focus or a large number of specimens or observations and so forth. Do not include notes such as "the strength of our collection is due to our sponsors".
The field Documentation state is meant to give users information about the type and format of the documentation – whether it is in paper form (such as card files) or electronic form (such as Excel files or a relational database). General estimations about the quality of the documentation, such as "good", "poor", and "satisfactory" are not appropriate.
Make sure that data you enter in the Publications field is clear and traceable. Do not simply enter the number of a publication without a name or clear reference for it.
If you are unsure about whether certain data belongs in a particular field, contact the support at support@biocase.org with any questions you may have.
Keywords
Free text descriptions are useful for readers viewing a result, but it is important to include keywords as well since user searches are conducted with the use of keywords. Keywords are significant terms that describe a collection. They can be entered under the Keywords tab in Nodit.
Keywords that are linked to an organization record should describe the organization as a whole - not specific collections that the organization contains. Instead, create one or more collection records as part of an organization and link the keywords to the collections they describe.
Every keyword record should contain only a single keyword. Do not include several keywords in a single record. Entries like "flies, dragonflies, beetles" or "1925, 1945", or "Orthoptera and Heteroptera" are not appropriate. Instead of a single keyword containing “Orthoptera and Heteroptera”, create a taxon keyword entry for "Orthoptera" and another taxon keyword entry for "Heteroptera".
Do not include numeric content in a keyword text field where it is not appropriate. The only types of keywords that should have numbers in them are time period keywords. Entries for common name keywords such as " Pigeons and Doves, in 45 genera" or geospacial keywords such as " Umkreis von ca. 100 km um Burghausen" are not appropriate.
Keep keywords specific. Entries such as "All" for taxon or common names or "World" for geospacial names are not appropriate.
Be careful not to err when entering keyword types. Entering common names as taxons or taxons as common names will create confusion and adversely effect search results.
A taxon keyword can include terms at any level of the taxonomic hierarchy – from kingdoms to families to species and varieties. Even entering a keyword of "Plantae" is helpful since it will be excluded on animal searches.
Collecting time periods should be numeric and formatted as yyyy-yyyy (for an interval), yyyy+ (for a particular year onward), or yyyy- (prior to a particular year). Entries such as "last 300 years", "18th century", or "about 1900" are not appropriate. If you are not sure about the exact year then estimate a brief interval.