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 will likely have to be done sequentially; that is, upgrade from the prior version to the subsequent version, but do not skip versions.

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 6.0 to version 6.1

To upgrade, you will need to:

  1. Run the SQL upgrade script

  2. Replace the emerse.war with the updated one

  3. Set ds.dialect in emerse.properties

  4. Add a database driver to Tomcat’s lib directory

  5. Replace the emerse-solr.jar in Solr with the updated version

  6. Add a request handler to the document index configuration

You can download the files of the release (such as the SQL script or new war file) from the 6.1 release page on GitHub. You will need to be logged into your github account, and added as a member of the EMERSE project to see it. Email us with your GitHub username to be added.

The value of ds.dialect is the name of a Hibernate class that should match the database you use. For Oracle, this value should be:

emerse.properties
ds.dialect=org.hibernate.dialect.Oracle12cDialect

Next, you’ll need to add a jdbc jar to Tomacat’s lib directory. (This directory is in the installation of tomcat, next to the conf directory and webapps directory, and should contain many other jar files.) This depends on which database you are using. For oracle, you can download the jar here.

Finally, after replacing the emerse-solr.jar in the lib directory of the documents Solr index, you’ll need to modify the solrconfig.xml of the same index by adding the following line underneath the root element:

documents/conf/solrconfig.xml
<requestHandler name="/unique-mrns" class="edu.umich.med.emerse.solr.handler.MRNCountHandler"/>

Upgrading from EMERSE version 4.10.7 to version 6.0

Upgrading from EMERSE version 4.4 to version 4.10.7

  • In general to upgrade to version 4.10.7 from version 4.4, you will need to:

    • Replace the existing WAR file with the new WAR.

    • Run the 4.4 to 4.10.7 SQL update scripts

    • Update the emerse.properties file

    • Update to Java 11

  • Several database tables/columns have been dropped since they are no longer used. If you have data in these tables you may want to back them up first to preserve their data. The following have been dropped:

    <dropTable tableName="PATIENT_HISTORY"/>
<dropTable tableName="PATIENT_LIST_ENTRY_HISTORY"/>
<dropTable tableName="PATIENT_LIST_DOWNLOAD"/>
<dropTable tableName="PT_LIST_ENTRY_COMMENT_SNAPSHOT"/>
<dropColumn tableName="DOCUMENT_VIEW" columnName="document_pk2"/>

  • In the emerse.properties file the email property has been removed and replaced by two new properties called contact.url and contact.text. This is detailed in the configuration guide.

  • Other new properties have been added, such as a URL about who to contact for help, as well as a URL pointing to the EMERSE help guide, which defaults to the official guide found at project-emerse.org

  • It is a good idea to keep a copy of the old emerse.properties file to make sure that nothing is lost with the transition to the new version.

  • There are no changes to the Solr indexes when upgrading from version 4.4 to 4.10.6

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.