Appendix J. Things to consider when updating an existing BASE installation

Table of Contents

J.1. BASE 3.15
J.2. BASE 3.14
J.3. BASE 3.11.1
J.4. BASE 3.10
J.5. BASE 3.9
J.6. BASE 3.8
J.7. BASE 3.6
J.8. BASE 3.5
J.9. BASE 3.4
J.10. BASE 3.3.3
J.11. BASE 3.3
J.12. BASE 3.2
J.13. BASE 3.0
J.14. All BASE 2.x releases

This document is a list of things that may have to be considered when updating a BASE installation to a newer version. The Section 21.1, “Upgrade instructions” section only include the most recent information that is needed for updating the previous BASE version to the current version.

J.1. BASE 3.15

Consider upgrading to Java 11 (OpenJDK)

The next BASE release, BASE 3.16, will only support Java 11 or later. BASE 3.15 is the last BASE version that supports Java 8. Our recommendation is to upgrade to Java 11 as soon as possible. Note that Oracle no longer provide a free JDK or JRE. Instead, OpenJDK has to be used, which can be downloaded from

If you experience any problems with BASE 3.15 and Java 8 you could try removing the listed files from the www/WEB-INF/lib directory and then restart Tomcat.

  • java.activation-api-1.2.0.jar
  • jaxb-api-2.3.1.jar
  • jaxb-core-
  • jaxb-impl-2.3.1.jar

Consider upgrading to Tomcat 9 and PostgreSQL 11

We have started to test BASE with Tomcat 9 and PostgreSQL 11 and we have not found any problems so far. For new installations we recommend that Tomcat 9 and PostgreSQL 11 is used. Official support for Tomcat 8 and PostgreSQL 9 will be dropped in a future BASE version. For existing installations our recommendation is to start planning for an upgrade to Tomcat 9 and PostgreSQL 11.

Secondary storage support has been removed

The Secondary storage feature has been removed. Files that are located in the secondary storage will be marked as offline by the upgrade script. The recommendation is to replace this feature with an external files solution instead.

Spot images support has been removed

It is no longer possible to create new spot images or view existing spot images via the BASE web client. Existing source image files and zip archives with generated spot images have not been removed.

Customizations made in Tomcat's global web.xml file

In the configuration directory for Tomcat there is a web.xml file that define global options for all web applications. The settings in this file can be overridden per web application in the WEB-INF/classes/web.xml. BASE 3.15 re-defines the jsp <servlet> definition to make sure that JSP files are compiled with proper settings. Changes that have been made to the global web.xml file for the jsp <servlet> must be moved or copied to the web.xml file for the BASE web application.

J.2. BASE 3.14

The db.driver setting is no longer used

The JDBC driver to use is now found automatically based on the db.url setting in the base.config file. The db.driver setting can be removed.

The (very) old Authenticator API has been removed

The net.sf.basedb.core.authentication.Authenticator interface and other related code that was deprecated in BASE 3.3 has been removed. Systems that still use old authentication code need to replace this with a newer version before updating.

Changes to the authentication system

The authentication system has been updated to make it easier to install more than one external authentication manager. The changes are backwards compatible and existing authentication managers should still work as before as long as they are the only ones installed. However, the existing authentication managers will probably not work well if more than one is installed since they lack some features that are neccessary in order to cooperate with other managers. Before installing more than one authentication manager it is recommended that they are updated to newer versions.

Newer authentication managers typically no longer provide support for password authentication. If the intention is that some users still should be able to login with username+password, it is recommended that the Password login form is enabled. Go to AdministratePlug-ins & extensionsOverview and locate the Login form customization extension point to find it.

J.3. BASE 3.11.1

Free wells on bioplates

A bug that affected the free wells information on bioplates has been fixed. Existing bioplates may have incorrect number of free wells and can be fixed by running a special script. After installing the BASE 3.11.1 update, change directory to <base-dir>/bin/ and issue

./ free_wells -u <root login> -p <root pwd>

J.4. BASE 3.10

Changed permissions for annotating items

Before BASE 3.10 a user was able to create/change/delete annotations on an item if the user has WRITE permission on the item and READ permission on the annotation type. In BASE 3.10 several changes has been made:

  • USE permission is required on the annotation type to be able to create/change/delete annotations of that type. This may cause user to no longer be able to annotate certain items, unless their permissions are upgraded to USE. Users with READ permission can only read the annotation values.

  • A new permission level, ANNOTATE, has been introduced. In the permission hierarchy this sits between the READ and WRITE permission and can be used to give users permissions to manage annotations but not other properties of an item. All users with WRITE permission automatically get ANNOTATE permission so this change should not affect current users.

J.5. BASE 3.9

Incompatible API change Application API

The Application.getSessionControl() method for getting access to an existing session has been deprecated. A new version has been implemented that require that an external client id is specified. Extensions and other client application may stop working unless they are updated. See alos Section I.5, “Application.getSessionControl()”.

J.6. BASE 3.8 is no longer needed

It is no longer needed to run the script as part of the upgrade or installation procedure. The funtionality has been integrated into the regular scripts.

Incompatible API change in ServiceSessionControl

The ServiceSessionControl API for configuration and building Hibernate SessionFactory instances has been changed due the Hibernate 5 upgrade. This change affects extensions that use the API for storing their own data inside the BASE database. Extensions that use this API must be updated or they will not work with BASE 3.8.

J.7. BASE 3.6

Update to Java 8

BASE will no longer run with Java 7. Unless you have already updated to Java 8 you should do so before updating to BASE 3.6. Note that BASE 3.5 works with both Java 7 and 8 so the Java update can be made ahead of time.

Update to Tomcat 8

Tomcat 7 is no longer supported. We recommend updating to Tomcat 8 before updating to BASE 3.6. Note that BASE 3.5 works with both Tomcat 7 and 8 so the Tomcat update can be made ahead of time.

J.8. BASE 3.5

Biomaterial lists have been replaced with item lists

This is a major change that has caused a binary incompatibility in the BASE core API. If you depend on custom extensions or plug-ins that use the biomaterial list API this code must be updated before updating to BASE 3.5. Read more about the incompatibilities in Section I.8, “Biomaterial lists has been replaced with item lists”.

Consider updating to Java 8

Oracle is no longer supporting Java 1.7. We are recommending Java 8 for running BASE. Java 7 is still supported, but will be removed in the next version (BASE 3.6).

Consider updating to Tomcat 8

We have now tested BASE with Tomcat 8 and it seems to work without any problems. Support for Tomcat 7 will be removed in the next version (BASE 3.6).

J.9. BASE 3.4

Updating from BASE 2.17 is no longer possible

If you are still running an BASE 2.17 (or earlier) BASE version and want to update to BASE 3.4 you must first update to BASE 3.3 or earlier.

Web services support has been removed

As announced earlier web services support has been removed in BASE 3.4. If anyone require web services support or similar we recommend using the BASE extensions mechanism to implement exactly what is needed for that project and we also beleive that a simplier API such as JSON is preferable.

PostgreSQL users should change db.dialect

In base.config there is a db.config setting. Servers running with PostgreSQL as the database should change the dialect to org.hibernate.dialect.PostgreSQL9Dialect since the org.hibernate.dialect.PostgreSQLDialect has been deprecated.

J.10. BASE 3.3.3

Remaining quantity

A bug that affected remaining quantity calculations for biomaterial item has been fixed. Existing items may have been saved with incorrect remaining quantity and must be fixed. After installing the BASE 3.3.3 update, the existing remaining quantity values are fix by running a special script. Change directory to <base-dir>/bin/ and issue

./ remaining_quantity -u <root login> -p <root pwd>

J.11. BASE 3.3

Content security policy

The BASE web client now set a rather strict Content Security Policy that prevent browsers from executing code (including JavaScript) that is considered unsafe. Some extensions may cease to work due to this. Go to AdministratePlug-ins & extensionsOverview (after upgrading) to see if there are any warnings about this. Read more in Section E.1, “Content security policy” for information about how to relax the policy.

Java SE 7 is required

BASE now require Java SE 7. Servers with Java SE 6 or older should be updated to Java SE 7 before installing BASE 3.3.

Tomcat 7 is required

BASE now require Tomcat 7. Servers with Tomcat 6 or older should be updated to Tomcat 7 before installing BASE 3.3.

Web services support has been deprecated

The current implementation is most likely not very useful and has limited support for accessing information in BASE. Therefore it has been decided to remove the web services support in BASE 3.4. If anyone require web services support or similar we recommend using the BASE extensions mechanism to implement exactly what is needed for that project and we also beleive that a simplier API such as JSON is preferable.

J.12. BASE 3.2

Custom logging implementations must be updated

The plug-in functionality for custom logging has been converted to an extension point. The default database logging will continue to function, but custom logging implementations must be converted to an extension. See Section I.11, “BASE 3.2 release” and Section 27.8.10, “Logging managers” for more information.

J.13. BASE 3.0

[Note] Upgrading to BASE 3 is possible from BASE 2.17 only

If your BASE is an older 2.x version you'll need to upgrade to BASE 2.17 before an upgrade to BASE 3 is possible. Also note that since BASE 3.3 we no longer actively test the upgrade script. If upgrading doesn't work for a particular BASE 3.x version (where x > 2) please try to upgrade to BASE 3.2 first and then from BASE 3.2 to BASE 3.x.

[Warning] Make sure that you have a recent backup of the BASE 2.17 database

Before starting the upgrade from BASE 2.17 to BASE 3 ensure that you have a recent backup. If the upgrade fails you must restore the 2.17 database before you can try again. The upgrade only changes the 'static' part of the database, so you do not have to restore the 'dynamic' part or the uploaded files.

Old plug-ins and extensions may not work

The BASE API has changed in several places and it is not certain that plug-ins and extensions developed for BASE 2 works with BASE 3. The upgrade will disable all plug-ins and extensions that are currently installed. Before you upgrade we recommend that you go through all (external) plug-ins and check if there is an updated version. The recommended approach is to first upgrade BASE and then install updated versions of plug-ins and extensions following the instructions in Section 22.1, “Managing plug-ins and extensions”.

If there is no updated version of a specific plug-in you may try a manual re-installation of the old plug-ins. Follow the instructions in Section 22.1.2, “Manual plug-in registration”.

If there is no updated version and the old plug-in doesn't work with BASE 3, you'll need to decide if you really need the plug-in or if the upgrade should wait until a new version of the plug-in has been released.

Batch item importer changes

There are several changes to batch item importers that may affect current workflows and file templates used for importing data.

  • Sample and extract importers: The 'pooled' column is no longer used. Instead a 'parent type' column should be used with the parent type as a string value (BIOSOURCE, SAMPLE or EXTRACT). Existing importer configurations and file templates may have to be updated. If no parent type is specified the sample importer assumes a biosource and the extract importer assumes a sample.

  • Labeled extract importer: This has been deprecated and it is recommended that the Extract importer is used instead. We recommend that existing labeled extract importer configurations are re-created as extract importer configurations. The old labeled extract importer can be re-enabled, but note that the existing configurations still need to be changed due to the 'pooled' column is no longer used.

  • Hybridization importer: This has been deprecated and we recommend that the Physical bioassay importer is used instead. Existing hybridization importer configurations should be re-created as physical bioassay importer configurations.

  • Scan importer: This has been deprecated and it is recommended that the Derived bioassay importer is used instead. Existing scan importer configurations should be re-created as derived bioassay importer configurations.

[Note] Note
The deprecated importers can be re-enabled by an administrator from the AdministratePlug-ins & extensionsOverview page, but they are lacking features that are available in the new importers so this is not something that we recommend.

MySQL and PostgreSQL versions

We have only tested BASE 3 with PostgreSQL 9.1. If anyone experiences any issues with earlier PostgreSQL versions, we recommend an upgrade to PostgreSQL 9.1. This is a change since BASE 2 which was tested with PostgreSQL 8.4. Even though BASE 3 may work with older PostgreSQL versions, we don't have the resources needed to test and provide support for it.

We have only tested BASE 3 with MySQL 5.1 (no change since BASE 2). If anyone experiences any issues with earlier (or later) MySQL versions, we recommend an upgrade/downgrade to MySQL 5.1.

J.14. All BASE 2.x releases

We only support updating to BASE 3 from BASE 2.17. If you have an older BASE version and wish to update to BASE 3, you first have to upgrade to BASE 2.17. BASE 2.17 can be downloaded from the BASE download page. Documentation for BASE 2.17 is available as part of the download and at