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.4 to 6.5

Upgrading from 6.4 to 6.5 follows the usual steps of upgrading the database with the database script, and replacing the war file. However, after upgrading you should review the fields in the admin application.

The first thing I would do is consolidate fields that appear in every source into a single field with its source set to All Sources. This makes the admin interface less cluttered, and allows you to have a single filter on that field. I would also go through all the fields and make sure they are in the correct order, have the correct labels, and set to be displayed in the correct parts of the application. Review the admin guide for how this part of the admin page works.

fields duplicate

The following properties in emerse.properties are no longer respected:

  • search.facets.excluded

  • patient.hideName

Instead, you can configure the same behavior through settings on the fields. Unfortunately, since these are properties in the emerse.properties file, we cannot automatically migrate the configuration, so you must do this yourself. If there were any search facets you excluded (using the first property), go to the corresponding patient field, and uncheck the option "Show in Demographics Dialog, Charts, and Excel". This will duplicate the behavior of the search.facets.excluded property.

If you have set patient.hideName, then go to the NAME patient field, and uncheck all checkboxes there. This will hide the name like the property did.

Next, for fields you wish to set up filters on, except for fields such as CSN / Encounter ID which have a huge number of values, I would go to the values tab for that field, and click the update button. This will query Solr and pull in all values of the field, including their counts. It could take up to a minute, possibly longer, depending on how much data you have in Solr. After its pulled in the values, I would then go over to the attributes tab and set the filter UI based on how many values it found (shown in the Values in Database line). If it’s more than 100, I would set AUTOCOMPLETE as the filter UI, otherwise set CHECKBOXES.

field encounter id filter
field update
field updated
field set filter

For the CSN / Encounter ID field, I would just set the filter UI to be TEXTAREA which allows users to type in whatever IDs they have, and doesn’t store any IDs in the database, which would be wasteful since you don’t need autocomplete, and more IDs are always being added.

I would also go in and hit update on all the patient fields you know you have data with. They should have filters already set up on them by default, but you can change that if you wish. Hitting update will add counts to the values, and add new values from Solr if there are any.

patient field zero count
patient field nonzero count

Upgrading from EMERSE version 6.1 to version 6.3

To upgrade from 6.1 to 6.3, you will need to:

  1. Download and run the SQL upgrade script for your database

  2. Replace the emerse.war with the updated one

  3. Replace the emerse-solr.jar with the new one.

All files can be downloaded from the release page.

The emerse.war file should be in the webapps directory of the tomcat installation.

The emerse-solr.jar should be in the lib directory of the index files, which in the same directory as the documents, patient and patient-slave directories. This file may have a different name from prior versions so be sure to delete the old one; there should only be one file in the lib directory, unless you have other non-EMERSE plugins installed in your Solr instance.

If you don’t find an upgrade script for your vendor of database in the release page, please contact us and we can generate one for you.

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 Solr’s index directory (aka SOLR_HOME), 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.