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.|
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).
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 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.
The following properties in
emerse.properties are no longer respected:
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
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
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.
To upgrade from 6.1 to 6.3, you will need to:
Download and run the SQL upgrade script for your database
emerse.warwith the updated one
emerse-solr.jarwith the new one.
All files can be downloaded from the release page.
emerse.war file should be in the
webapps directory of the tomcat installation.
emerse-solr.jar should be in the
lib directory of the index files, which in the same directory as the
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.|
To upgrade, you will need to:
Run the SQL upgrade script
Replace the emerse.war with the updated one
Add a database driver to Tomcat’s
Replace the emerse-solr.jar in Solr with the updated version
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:
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:
<requestHandler name="/unique-mrns" class="edu.umich.med.emerse.solr.handler.MRNCountHandler"/>
Due to the substantial changes required for this upgrade, please see the separate 4.10.7 to 6 Upgrade Guide.
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 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"/>
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.propertiesfile 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
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.propertiesfile. This is described in the Configuration Guide and involves the two properties
Make sure that you define the email in the
project.propertiesfile 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.propertiesfiles 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.xmlfile. This file is located inside the
SOLR_INSTALL_DIR/server/etcfolder. Remove the line:
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.