Difference between revisions of "FAQ"

Latest revision as of 10:26, 15 August 2024

General

What is the BioCASe Provider Software and what can I use it for?

See the Beginner's Guide.

What do I need to use the BioCASe Provider Software?

See the requirements in the Beginner's Guide.

I’m not sure whether the Provider Software is the right choice for me. How do I find out?

Just contact us and describe your situation and what you’re planning to use BioCASe for.

How much is the BioCASe Provider Software?

It’s Open Source Software, so you can use it for free.

I am not affiliated with any institution. Can I use the Provider Software in spite of that?

Sure, you can also use the Provider Software as a private person.

Can I use the Provider Software on my operating system?

I guess. As long as a web server (such as Apache) and Python are available for your operating system, you can – and they are for most operating systems.

I cannot meet all of the requirements for installing the BPS. What options do I have?

Basically, there are two options: If you still want to use BioCASe (maybe because you owe very rich data and need the comprehensive ABCD schema for publication), you might ask a partner institution already using BioCASe to host your data. In this case, you would send the database (or Excel file) to this institution, where it would be published using the existing BioCASe installation. You would still remain owner of the data and attributed accordingly on the data portals; the partner institution would act merely as a technical host (like a commercial internet host).

Another option would be to use one of the tools offered by GBIF. With the Integrated Publishing Toolkit (IPT, http://www.gbif.org/ipt) you can create a DarwinCore Archive (see http://rs.tdwg.org/dwc/terms/guides/text/index.htm for more on DwC Archives) from your database, which you would send to GBIF for publication. The GBIF Spreadsheet Processor (http://code.google.com/p/gbif-spreadsheet-processor/) is a similar tool intended for smaller occurrence datasets stored in Excel files. The downside for both is that they support only the DarwinCore standard, which is rather limited in comparison to ABCD.

I have some recommendations/bug report. How can I file it?

You can either leave a message on the respective Discussion page or get directly in contact with us.

Installation

After installing BioCASe, I get a "500: Internal Server Error"

1. Make sure you've run the setup script after downloading or checking out BioCASe with the right Python version. To check this, open the file www/index.cgi of your installation in a text editor and check the first line: This is the Python executable used by Python.
2. Empty the folder cache of your installation - please remove all folders and files you find here.
3. If the problem persists, please contact us!

When typing in the URL for my new installation (http://localhost/biocase), I get an empty page or a “URL not found” error. What’s wrong?

If you get a blank page, that’s probably because Apache (or the web server you use) is not running. Start it and retry. If you get a “The requested URL /biocase was not found on this server” or similar message, the web server doesn’t find your BioCASe installation. Go to the section Linking BioCASe and Your Web Server of the Installation guide and follow the instructions.

When typing in the URL for my new installation (http://localhost/biocase), I get an “Internal Server Error: The server encountered an internal error or misconfiguration and was unable to complete your request” message.

You’re probably using Apache, which cannot find your Python installation. Make sure you’ve installed Python correctly and did run the setup script (see sections Installing Apache/IIS and Python and Running the Setup Script in the Installation guide).

I'm using Internet Information Server, and after creating the Virtual Directory for BioCASe, I get a “502.2 - Bad Gateway. The specified CGI application misbehaved by not returning a complete set of HTTP headers” error.

This happens when you didn't correctly associate .cgi and .py files with Python. Make sure you've linked both files with Python and that the path contains the placeholders %s %s (see Linking IIS).

I cannot find the installation package of the database connectivity module for the DBMS and the Python version I am using.

You’re probably using one of the newer Python versions which are not yet supported by the DB package you want to use (that’s the reason Python 2.5 is recommended). Just install an older version (2.5 or 2.6). You can have several Python versions installed on the same machine, so you can keep the newer version for other applications and install the older version for BioCASe.

I’ve installed the Python package for my DBMS, but it doesn’t show up in the Test libs page. What’s wrong?

Python packages are Python version specific and you’ve probably installed the DB package for the wrong Python version. If you have several Python versions installed on your machine, make sure you installed the package for the version that is used by BioCASe.

I’m using Postgres and installed the psycopg2 lib for that. When connecting, I get a pink error message “A problem occurred in a Python script”; the last line of the error messages reads “psycopg2._psycopg.connection object has no attribute server_version”.

This is caused by an outdated psycopg2 version. Please install version 2.0.12 or later of psycopg2.

I'm trying to use BioCASe with Postgres; for this, I tried to install psycopg on Windows. But it doesn't work - either the install crashes, or it finishes, but the test libs page still reports psycopg2 as not installed. In the debug log I can find the error message "ImportError: DLL load failed (...)". What's wrong?

We suspect this is caused by a bug in recent psycopg2 releases (find more here). On our test installations, we managed to get round this issue by installing pycopg2 with administration rights. Do do this, right-click the installer file and choose "Run as administrator".

What's the difference between the DBMS packages odbc_tsql and odbc_tsql_2012 and between pymssql/pymssql_2012, respectively?

The dbmods ending in "2012" use the new OFFSET clause that was introduced in MS SQL Server 2012. This will make paging faster and increase performance for larger datasets. They work only with SQL Server 2012 or later, and if you use SQL Server 2012, you should use them for best performance. Dbmods without a trailing "2012" work for both older versions and SQL Server 2012, but will be slower in paging large datasets.

I have problems installing GraphViz. Do I really need it?

If installed, Graphviz will create a graph of the table you've configured with their primary/foreign keys and the relations between them on the Database Structure page. If you have more than just a few tables and lots of relations between them, this can be very useful. If you don't need this feature, you don't need to bother installing GraphViz.

I’ve installed GraphViz, but it doesn’t show up as being installed on the Test libs page.

You need to tell BioCASe about the location of the GraphViz files, since it is not a Python package that will be registered automatically. In order to do so, locate the Graphviz installation on your local disk. Go to the System Administration and enter the path to the binary executable into the text box labelled Graphviz dot binary. On Linux machines it might look similar to the default (/usr/local/bin/dot), on Windows machines it will be probably something like C:\Program Files\Graphviz2.26.3\bin\dot.exe. Press update config to save the path.

I want to update my BioCASe installation. How do I do this?

See Updating an existing BioCASe Installation.

I've updated my installation from a version prior to 2.6. Now, when I enter the DB structure, some of the table and column names are gone, the same happens in the mapping editor.

Starting with version 2.6, BioCASe retrieves table and column names from the database for some database management systems (namely MySQL, SQL Server, Postgres, Foxpro, Access and Oracle). In older versions, you had to enter table/column names manually, and when you did the setup with such an early version, you probably didn't care for upper/lower cases. Since some DB management systems are case-sensitive, BioCASe can't ignore the differences and won't find these technically incorrect names in the lists retrieved from the database. The respective drop down boxes will therefore be empty. If that happens, just select the correct names from the drop down lists.

When I try to create an archive, I get a "Permission denied" error. Why is that?

For creating archives, you need to grant write permissions for the folders archive and www/downloads of your BioCASe installation to Python. You can check if permissions are set correctly in the test libs page (Start --> Utilities --> Test Libs).

I'm trying to install BioCASe on Ubuntu (or another Linux). Even though I've run the setup script and added the snippet to the Apache configuration file, I see source code when I try out my installation instead of the pages described in the documentation

Apparently CGI is not enabled on your machine. Google how to enable CGI for your distribution and follow the instructions you'll find.

When trying to run BioCASe after installation, I get an internal server error (500). But the log folder of BioCASe is empty, nothing to find.

This is probably because BioCASe - or the web server that runs BioCASe - can't write to this folder. Make sure that the web server (user www-data for Apache) has write permissions for this folder.

I'm running BioCASe in a Docker container and I can't connect to a local MS SQL Server (on the same machine, but not in a Docker)

Do not use host.docker.internal:host-gateway (e.g 172.17.0.1) to connect, but the external LAN IP, often like 192.168.0.x or 10.x.x.x.

Debugging

I’ve mapped ABCD2. In the result document, each record of the dataset becomes a single dataset, even though there is just one dataset in the database – what’s wrong?

That’s probably because you’ve mapped a metadata element to a table that holds several rows for this dataset, so for each row a different dataset gets created. It doesn’t matter whether the values for that field are effectively different from each other; rows are distinguished from each other only by their primary keys.

I’ve mapped ABCD2, and in the result datasets I get several units for each record, each with the same UnitID.

That happens when you map a non-repeatable element of ABCD to a database column that has several rows for one record. In order to create a valid ABCD document, for each of these values a new unit gets created by the Provider Software. To solve this, remove the multiple values or map them to a repeatable element.

I've mapped ABCD2. When testing the web service, I get a negative number for "RecordsDropped" in the response document. What does that mean?

Same problem as above - it means you have an error in your mapping. Most probably you've mapped a non-repeatable ABCD concept to a table/column in your database that holds several entries per unit (occurrence) record. The BioCASe Provider Software will duplicate the respective unit records to be able to create valid ABCD documents - which is indicated by a negative number of "records dropped". Make sure the cardinality of your database relations match the structure (in respects of element repeatability) of ABCD to avoid this problem.

I'm using pymssql to connect to a SQL Server database. Char(n) and Varchar(n) strings get truncated to 255 characters - what's wrong?

This is known limitation of TDS protocol used by pymssql. Just change the data type for columns storing long string to TEXT or create a view that converts Char/Varchar columns to TEXT columns on the fly to work around this issue.

I'm using pymssql to connect to a SQL Server database, BioCASe is running on a Linux distribution. When I do a Search or Scan request, I don't get any results (0 hits), even though there are definitely records in the database.

That problem occurs on old versions of pymssql (1.0.2 or earlier) on Linux distributions. Update to version 2.0 or later to solve this. If you still get empty result sets, these posts might be helpful:

• http://open-up.cybertaxonomy.africamuseum.be/forum_topic/important_if_you_use_biocase_bps_linux_platform_connect_ms_sql_server
• http://code.google.com/p/pymssql/issues/detail?id=76.

The database connection status is No Connection, even though I’ve selected the correct DBMS in the connection settings dialog and entered the credentials into the text boxes.

Check whether you’ve installed Python package for the DBMS you’re using (test libs page). If you still can’t get a connection, turn on debugging (in the System Administration dialog) and go to the database settings dialog again, press Save to retry connecting. Then see the log files (in the log folder of your biocase installation) for more detailed error messages.

I am using BioCASe on a Windows Server. For some queries with the Local QueryForm, I get an error page that is obviously produced by the web server and not BioCASe. It reads "Error Code: 500 Internal Server Error. The request was rejected by the HTTP filter. Contact the server administrator. (12217)"

This happens when BioCASe is run behind a Microsoft ISA Server/Microsoft Forefront Threat Management Gateway. To solve this problem, follow the instructions given in this article: http://support.microsoft.com/kb/837865.

The information that can be found in the log files folder is too sparse – what can I do?

Turn on debugging in the System Administration.

How do I find out if my BioCASe web service works right?

Use the Query Form to send a BioCASe request to your web server and check the result document (see the Debugging guide and the Sample ABCD document for more).

I’ve copied a schema mapping for a datasource from an older installation by placing the cmf_ABCD_2.06.xml in the datasource configuration folder, but when querying the datasource, I get a “schema is not supported by this provider” error.

The Provider Software keeps a list of supported schema mappings in the provider setup file. Just open go to the mapping editor for the schema in question, press Save (without having modified anything), then go back to the overview page of the datasource configuration. The Provider Software will then update the list of the supported schemas.

When using the local Query Form for debugging, I don’t get any results, even though my web service is working. On pressing Submit, I get a timeout after about a minute.

That’s probably because the domain configured in the BioCASe System administration is not correct. The default localhost works only if you’re using the query form directly on the server machine. If you’re using them in the browser window of another machine, the domain needs to be configured correctly with the IP address or the full server name (e.g. ww3.bgbm.org).

I mapped the ABCD concept FullScientificNameString. But when running the Search test (which includes a filter on the scientific name per default), I still get the error message "The requested concept /DataSets/DataSet/Units/Unit/Identifications/Identification/Result/TaxonIdentified/ScientificName/FullScientificNameString is not searchable for this provider! Please do a capabilities request to see all searchable concepts." What's wrong?

The element FullScientificNameString exists twice in ABCD 2 (as the whole TaxonIdentified tree that surrounds it): once for the Identification object under the path above, and then in the Synecology branch (/DataSets/DataSet/Units/Unit/Gathering/Synecology). This can be a bit confusing, and probably you've accidentally mapped the wrong concept. Change the mapping, and it should work.

I'm using BioCASe in a Vagrant Virtual Box on MacOS with Synced Folders. When using the Manual Query Form or the Archiving page, I get an "ImportError: No module named wrapper.errorclasses."

We don't know exactly what causes this, but apparently it happens when BioCASe is run in a Vagrant Virtual Box on MacOS and Vagrant's synced folder are used. We do have a workaround for this, but it is not easy. Please contact us for assistance on this.

I'm using BioCASe on a Windows server and odbc_tsql to connect to an MS SQL Server. Even though I do get results for a SCAN request, I cannot do a SEARCH (invalid document received).

Please check your encoding settings in the DB connection configuration. If it is set to UTF_8, try Latin_1 instead.

Trouble Shooting

I’ve forgotten the password of my BioCASe installation. What should I do?

Just go to the config folder of your installation and have a look into the file config.ini.

In the mapping editor, I am trying to insert a literal that contains a non ASCII character. When saving, the system directs me to a page that allows me to change the system encoding to UTF-8. Unfortunately, on my installation there is no such file as printed in the technical description; as a result, I get an enoding error in the Provider Software later on.

First of all, read the paragraphs on the disadvantages of mapping literals in the Beginners Guide and consider storing the information in a database table instead of mapping it as literals. Then, just move the data to a table and map the database columns. If, after thinking it over again, you still want to map literals with non-ASCII characters, you need to do the following:

• Go to your Python installation (for example /usr/lib/python2.5),
• Create the file sitecustomize.py in the subfolder /site-packages with the following two lines:

import sys
sys.setdefaultencoding('utf-8')

• Save the file and retry. Maybe you'll have to restart your machine for the changes to take effect.

I get a nice pink “A problem occurred in a Python script” error. What’s wrong?

Probably something happened we didn’t foresee, or you might have just found a bug. Please take a screenshot of the screen and write down what you did to make this happen. Then contact the BioCASe team.

I run into problems when installing/configuring the Provider Software. Neither the tutorials nor these FAQ I am looking at now can help me.

Just contact us; we’ll try our best to help you.