EMERSE Additional Operational Considerations Guide

This guide contains additional considerations that one might want to address regarding the ongoing operation of EMERSE. A few considerations regarding deployment are covered as well.

One important consideration for EMERSE is how much data should be loaded into the system, or how far back in time the data should be loaded. This will depend entirely on the institutional requirements for its use, but a few things should be considered. First, EMERSE can organize data by source systems, so if you have older, legacy data, then those data can be loaded as its own source. Second, because it is a search engine, adding more data is easy because EMERSE should have no problem searching through the extra data—​in fact, that is what a search engine is meant to do. Because it is hard to predict future data needs, and because of the small incremental effort for loading additional data, unless there are reasons not to load all of the available data, it would be a good idea to make it all available for the users.

Several sites have asked about how much data should be loaded for an initial pilot of EMERSE. For a variety of reasons, sites may not want to load all of the data at first, especially when including just a small subset of users to try out the system. In such a situation it may be important to first determine who those users might be and what their data needs are. For example, should all data for a small subset of patients be loaded into the system? Or should 1 or 2 years of data for all patients be loaded into the system? One important consideration if choosing the latter option is what the implications might be if older data are not loaded for a patient. In such a case, it might be problematic if a user searched a patient, found nothing, and then assumed the disease or condition didn’t exist for the patient because the older documents mentioning the condition were not loaded. Whatever decision is made, it should be made clear to the users what the implications are based on the type, volume, and time frame of the data that were loaded (versus what was intentionally left out).

EMERSE is meant to search the free text from documents. With the Advanced Terms feature it may be possible to search additional metadata if the data are loaded properly into the Solr indexes. However, for many users it may be even more valuable to append additional metadata or structured data to the document itself, making those elements searchable even if those data were not initially created to be a part of the original document. For example, it might be useful to append the current medication list or problem list to the document before it is sent to Solr for indexing. It might also be useful to provide billing codes, the name of the clinician who authored the note, etc. By doing so this additional information becomes a searchable part of the document and thus easy for users to find with standard EMERSE searches.

For example, in the text below all of the text preceding "Clinical Text:" could have come from structured data and just appended (pre-pended) to the beginning of the note to provide additional searchable text about the clinical encounter. Such choices will have to be institution-specific but additional data will likely be of great value to users.

An important decision to make regarding adding documents for indexing relates to whether or not incomplete, or unsigned, documents should be included. Generally, once a document is signed it can no longer be changed, although it can be addended. Unsigned, or incomplete, documents can be provisional and may require further editing or review by the clinician to make corrections or to include additional information. Including unsigned/incomplete documents means that they might be available to EMERSE users faster than their signed/completed counterparts, but the trade-off is that the users may be looking at provisional notes that could contain inaccuracies that would later be corrected before the clinician finalized and signed the document. While there are no specific guidelines about the best approach, these trade-off should be considered carefully when making the decision on what notes to include or exclude. At Michigan Medicine, only signed documents are included within EMERSE.

Users often want to know how quickly a document will be available in EMERSE once it has been created within the EHR. This will depend partly on your process for moving documents from the EHR to EMERSE, or from the EHR to an intermediate data repository, and then from the repository to EMERSE. At Michigan Medicine we update the index once each day, around 3 AM. This means that a document that arrives in our document repository shortly after the indexing process is complete might sit unindexed for almost a day before it was available within EMERSE. For some users this delay might not matter, but it will be important to make sure users are aware of possible delays in document availability within EMERSE, and to make sure that such delays are acceptable for the intended uses. There is nothing to prevent more frequent, incremental indexing from occurring, but it will be important to make sure that the hardware available can handle indexing updates and concurrent use during the day.

There is no separate command to index a document once its been sent to Solr. There is a concept of "commit" such that updates may not happen immediately unless a commit is added to the update. Generally Solr decides when enough data or updates have been sent that it is worth a commit.

Patient/Document merges and splits occur routinely within medical record systems. Both involve re-assigning documents to a new (corrected) medical record number. A merge occurs when a patient has been assigned more than one medical record number, and thus the documents may be listed under more than one medical record number. To remedy this, the medical record numbers are merged into a single MRN and the documents then get reassigned to the single MRN. A split occurs when it turns out that a set of documents for a single patient have been incorrectly assigned and actually belong to more than one patient. In this case the documents have to be re-assigned to the correct patient MRN, which can potentially be to more than one person.

There are several implication of merges/splits for EMERSE, and it means that these merges/splits have to be tracked in some manner to ensure that any changes to documents within the EHR get reflected back into EMERSE. For example, if a document repository is maintained for providing documents to EMERSE, that repository will need to keep track of these changes and subsequently submit these changes to Solr for re-indexing. From a very practical perspective, the following are some activities that will likely need to be considered for long-term operational maintenance of EMERSE:

This also has implications for sites that want to include older documents from a legacy medical record system, since those documents should also be subjects to splits/merges if the patients are still active within the newer electronic health record system and documents or MRNs are incorrectly assigned with respect to data in the legacy EHR.

Dealing with splits/merges from an operational perspective will take some planning. With a large set of Solr documents, re-indexing all the documents regularly will not be practical.

When indexing documents incrementally, depending on the mechanism used to detect changed documents, it may not be possible to detect that there are documents whose patient MRNs have been modified. To overcome this challenge at Michigan Medicine, we have a Pentaho Data Integration (PDI) job that runs regularly to read the history of all MRN merges/combines, and updates any documents in the Solr index that exist on the patient’s prior MRN. Michigan Medicine can share the PDI job that does this upon request, but the main points are:

In Epic’s Clarity datastore, the following SQL can be used to generate a list of MRN’s that have changed:

Finding documents in Solr for a specific MRN:

Where documents is the name of the main Solr index and med_rec_num should be replaced with an actual medical record number.

Images in clinical documents can be important for interpreting the results, meaning, and context of a patient encounter. This should be taken into consideration when indexing documents from sources in which images are routinely embedded within a a document. Heavily impacted specialties may include dermatology (e.g., photos of skin lesions), ophthalmology (e.g., drawings and retinal photos), or even cardiology (e.g., ECG tracings).

EMERSE can support displaying images within documents as long as they are encoded using Base64, which is an encoding scheme that converts binary data to a string of ASCII characters. Multiple encoders exist to do this, but the general format will look something like:

In fact, the EMERSE logo below is encoded within this web page using Base64 (view the page source to see the encoding). This approach is advantageous because external images do not need to be stored elsewhere and retrieved for display (with concurrent issues of having to update/delete images as documents are updated or deleted). The downside of this encoding approach is that the documents will be larger and thus more storage space will be required (the image below is 67k as a PNG file and 90k when encoded with Base64).

EMERSE itself does not provide the encoding software for images, but such an approach may be worth considering as part of a documenting indexing pipeline. Michigan Medicine started incorporating images into documents indexed within EMERSE as of 2021. It should be noted that the images are there to help with interpreting the overall document, but any text within the embedded images is not currently searchable with EMERSE.

Many sites have documents from outside sources, or potentially from internal sources, that are not in either a plain text (.txt) or standard web-based (.html) format which are the main two document formats that Solr can natively handle. In such cases there are ways to extract the text and import it into EMERSE. Examples of these files types include Adobe PDF or Microsoft Word (.docx) documents. For these cases, additional components and steps may be required to extract the text. Apache Tika is a tool that can help with this task.

Documents that are scanned images present additional challenges, and this is addressed in the section below on Optical Character Recognition.

Unlike some natural language processing systems, EMERSE shows the original clinical documents to users, with the terms of interest highlighted. Thus, it is highly recommended to use formatted documents within EMERSE. EHRs such as Epic allow users to create formatted notes (tables, bold text, italics, etc) and this additional formatting can help to convey information and can help users interpret the data in the proper context. Without such formatting, the original meaning can be difficult to interpret. For example, the two figures below show an example of the same note, first unformatted and then formatted.

Unfortunately, many document repositories, including Epic Clarity, often contain documents stripped of all formatting (with the exception of line feeds). It is worth spending the time to identify approaches for retrieving the original, formatted version of the notes. EMERSE can natively handle plain text documents, but it can also handle HTML documents. These HTML documents can preserve the formatting that can make the notes much more readable. Details about how to obtain formatted Epic documents can be found in our Integration Guide. Epic natively stores documents in RTF format, and directions for converting RTF to HTML can be found below.

Many EHR documents are stored natively using the rich text file (RTF) format. Solr does not natively handle RTF files, so it will be necessary to first convert them to either plain text (TXT) or, preferably, HTML since HTML will preserve a lot of the formatting of the original document. There are multiple approaches for converting RTF to HTML format, a few of which are described below. It may be worth trying various options on your actual documents since the output between converters can differ.

Documents that are images present a challenge for incorporating the text into EMERSE. A PDF file, for example, might contain actual text within the document structure, or it may contain an image of a document that has text, but that scanned/photographed/imaged text cannot be not readily extracted. These images could arrive at a clinic through a variety of means (e.g., hand-delivered by patients, faxed, etc.), but if the long-term storage strategy for storing the documents is scanning and archiving the images, then the text will not be readily extractable. For example, our strategy at Michigan Medicine is to scan a paper document and then store the scanned image within an institutional document repository using Hyland OnBase. The paper version is then destroyed.

Optical Character Recognition (OCR) provides a means for essentially conducting image analysis on a document, and recognizing and extracting the text to make it capable of being indexed in a system such as EMERSE. While EMERSE itself does not have built-in OCR capabilities, OCR could be used as part of a document-processing pipeline that identifies and extracts texts prior to submitting the documents to EMERSE for indexing. We have conducted various proof-of-concepts to show that this is possible, and some scanned/OCR’d documents can be found in our online demonstration system. We have had experience using both commercial (e.g., Nuance) and open source (e.g., Tesseract) OCR options.

Most OCR software will recognize printed text, but will not recognize hand-written text. Nevertheless, we have found that OCR can still be useful in cases where the main item of interest may be hand-written, but a search for related text in a document header can still rapidly bring the user to the right page among hundreds or thousands of potential documents.

Our experience with Tesseract has shown that it generally works well, but it performance depends heavily on the quality of the original document image, including how fuzzy the images its, its horizontal orientation, or other extraneous marks (such as handwriting) covering the text. A few examples of images and corresponding extracted text are provided below.

At Michigan Medicine, EMERSE users can access the system via two primary routes. The first is logging directly into EMERSE, once an account has been created for the user. A second option has also been made available to users in order to streamline the process for conducting a search after reviewing a patient within the electronic health record (EHR), which is Epic at Michigan Medicine. In this latter case, a user must first open a patient tab (workspace) within Epic, which will reveal a set of options from a button in the workspace. At Michigan Medicine this button is named "More" and provides access to many other options within Epic itself but also links to outside systems such as EMERSE. We have a submenu set up called "Other Clinical Systems", and one of these systems is EMERSE.

When a user chooses EMERSE from this Epic Menu, a browser is automatically opened and the Epic user will automatically be logged into EMERSE and they will land at the Attestation page, which is where the user specifies the intended use of EMERSE for that session. Further, we have provided default text in the EMERSE Attestation text box for this specific scenario which essentially says "search from Epic". The user could change this Attestation reason, or just submit the default answer. Once the Attestation is completed, the user will move to the main work area of EMERSE, and the patient that was opened in Epic will also be loaded within EMERSE. This means that a search can be conducted on that patient right away. In other words, from the user’s perspective the steps from the EHR would be:

Security details about how the data and user’s credentials are passed from Epic to EMERSE will vary for each institution. However, the documentation on the Epic site regarding "Integrating External Web Applications into Epic" is an ideal place to start learning about how to do such integrations. There may be other ways to provide such integration, but we describe our current setup to illustrate how this could be done.

EMERSE system errors are logged, which may be helpful in tracking down issues. These EMERSE system errors can be found in the tomcat_install_dir/logs directory. They will be in a file called catalina.out as well as a file called emerse.log. Logging is controlled by a log4j2.xml file which can be found inside of the expanded emerse.war file.

Some of the logs can be accessed through the EMERSE Administrator application or the diagnostics.html page. For more information about these options, please see the Troubleshooting Guide.

Each site will have to determine their own local rules and guidelines for who should be permitted to gain access to EMERSE, especially since patient information can be viewed. At Michigan Medicine the following guidelines were implemented:

EMERSE uses Apache Solr for indexing documents. Over time the index can become more fragmented and less efficient. This issue can be addressed by optimizing the index periodically. Index optimization is time- and space-intensive, so we recommend doing this about once every 3-4 months. Additional details can be found in the Configuration and Optimization Guide.

The EMERSE source code is stored in a private Github repository, and access is available upon request. Since this is an application that interacts with protected health information, we will only provide the source code to 'trusted' collaborators. We ask that anyone who has the source code stores it in a repository where access can be restricted to trusted individuals. Providing unrestricted code online could invite someone with ill-conceived intentions to look for ways to hack the system, and our goal is to reduce this risk as much as possible. Additionally, it is important for us to be able to track installations of the system since such metrics are important to our funders.

In a production environment, EMERSE, as a web application running inside the Tomcat application server, usually requires a reverse proxy server on top of Tomcat so the traffic can be redirected through HTTP on port 80 or HTTPS on port 443.