Overview

This guide provides directions on how to upgrade an older version of EMERSE to a newer version. We are not able to support all versions of EMERSE indefinitely, so we recommend upgrading the system whenever updates becomes available.

In general we will support upgrades from one publicly released prior version. If upgrading from an older version that is not the prior one, multiple upgrades may have to be done sequentially.

We update the software on a routine basis, but not all versions are released publicly. This is to reduce the number of versions used by other sites and to reduced the number of upgrades that will be needed. Our goal is to release a public version of EMERSE approximately every 6 months. If a vital bug fix is needed (for security purposes, for example), we will release the software at a more rapid interval.

Database Table Modifications

We are using Liquibase as a tool to keep track of database changes (adding/dropping/renaming tables, columns, etc). Liquibase outputs SQL scripts to update these tables, which can be run locally to make any needed changes. If you have modified any of the standard tables within EMERSE, these update scripts could create conflicts. However, if you have created new database tables within EMERSE, these additional tables should not cause a problem since the update scripts would only make changes to the standard EMERSE tables.

The only exception would be a situation in which you created a database table with a name that ended up being the name of a new table that was created for the default EMERSE distribution. To avoid this, just make sure you name any new tables you create locally in a way that it would be highly unlikely to ever conflict with a name that the standard distribution would use (you could add the name of your institution to the table name, for example).

Version Specific Upgrade Notes

These include specific items that must be considered when upgrading from a specific version, mostly when new changes may affect how the system is configured, and were not present in earlier versions.

Upgrading from EMERSE version 3.5

  • Several database tables have been updated. We are providing several SQL script to update these tables as part of the release. We will provide these updating scripts upon request.

  • Changes have been made to how Hibernate assigns sequence numbers between version 3.5 and 4.4. Therefore, you will need to run a validation script to validate the setup (V41_CHECK_SEQ_PROC), and if there are no concerns, then proceed to updating the sequences with the update script (V41_UPDATE_SEQ_PROC). Please contact us if you have any questions about this change. We strongly encourage you to first make any changes in a test environment.

  • If you have modified the EMERSE source code to change or add new tables to the EMERSE DB using sequences, then please contact us to discuss how to make sure the the update scripts work properly with your custom changes.

  • Make sure that you define the two timeout properties that are now defined in the project.properties file. This is described in the Configuration Guide and involves the two properties application.idle.timeout and application.warn.length.

  • Make sure that you define the email in the project.properties file since that is now where this is defined. This is the email that is used to send feedback from users to the local EMERSE team.

  • In general, check the project.properties files carefully for any additions that may not exist in the prior file. Some of these may not matter much since if they are missing they will be set to default values. Additionally, make sure that prior properties are preserved if replacing the file with the new one.

  • If you have set up Basic Auth, you will have to remove a line from inside the <Configure></Configure> tags within the jetty.xml file. This file is located inside the SOLR_INSTALL_DIR/server/etc folder. Remove the line:

    <Set name="refreshInterval">0</Set>

  • Moving from EMERSE version 3.5 to 4.4 involves upgrading Solr to from version 6.0.0 to 7.3.1. Because the Solr indexes are formatted differently between these versions, the indexes also need to be updated. Directions for doing this are detailed in the Solr 7 upgrade guide.