Overview

This guide is meant to provide additional information about troubleshooting various problems that an admin/developer may run into. Additionally it provides guidance on other issues that may be helpful when operating the system if certain problems arise.

If you do run into problems and need our assistance, please be prepared to provide screen shots of the error messages as well as log files.

Log Files

The log files may be very helpful in tracking down problems with EMERSE, and will likely be needed if you need to contact the EMERSE development team for technical support. To help with troubleshooting we have built a basic Log Viewer into EMERSE.

The Log Viewer is available in both the EMERSE Admin Application (see: Administrator Guide) and on the diagnostic checklist page (see: Installation Guide). Note that on the diagnostic checklist page, the log files are only accessible if a hardened profile has not yet been activated. Otherwise it will be necessary to login to the Admin page to view the log data.

The viewer shows recent content from the EMERSE application log. The log may show details of a configuration problem, or other unforeseen errors while EMERSE is running. This log does not show errors from Tomcat itself. The default configuration will only show errors, but it can be optionally configured to show debug and tracing output.

The log feature is only available if the log4j2.xml file, inside the deployed WAR file (WEB-INF/classes/log4j2.xml), has an included appender for EMERSE. The default EMERSE distribution already has this enabled, but if you wish to confirm or have more manual control over the log4j configuration, the relevant portion of configuration is shown below.

<Configuration status="warn"><!--  set status="debug" for lots of info from log4j iteself -->
<Appenders>
	<Console name="STDOUT" >
		<PatternLayout>
		<pattern>%p: [%d{ISO8601}] %c.%M()%L %m%n</pattern>
		</PatternLayout>
	</Console>


	<EmerseApplication name="EMERSE" numBuffers="10" bufferSize="10000">
		<ThresholdFilter level="ERROR"/>
		<PatternLayout>
			<pattern>%p: [%d{ISO8601}] %c.%M()%L %m%n</pattern>
		</PatternLayout>
	</EmerseApplication>
</Appenders>

To show additional, non-error messages in the EMERSE application log, the level setting above can be modified to a different value. Valid values are: TRACE, DEBUG, INFO, WARN, and ERROR.

For example:

<ThresholdFilter level="DEBUG"/>

Documents Not Showing Up in EMERSE

If documents added to the index are not showing up in EMERSE, it may be because the Solr index needs to be refreshed, or EMERSE needs to be made aware of the changes. This behavior might occur especially during initial setup and testing where a document is added to the index but then is not visible within EMERSE. Sometimes this behavior might be manifested in a case where a document can be identified during an All Patient search, but then isn’t visible when using a Patient List or within the Overview section of the EMERSE user interface. To force EMERSE to see the document index changes immediately:

  • Login to the EMERSE application under the admin role, and complete the Attestation page.

    http://emersehost:port/emerse/login.html

  • Visit the following URL and press return:

    http://emersehost:port/emerse/springmvc/admin/refresh/indexes

This should allow the EMERE application to see changes in the Solr index files, once the indexing is complete.

Patient Indexes

Rebuilding Patient Indexes

There may be times when the need arises to rebuild the Solr patient indexes (patient and patient-slave). For example, if you are working on setting up the system and have just added patients to the database table, that change won’t be reflected within EMERSE immediately since typically the patient data are copied from the Patient database table to the Solr patient index only once per day through a scheduled job (see: Configuration Guide).

To force the copying/indexing to happen on demand, the following directions describe how this can be done.

  • Login to the EMERSE application under the admin role, and complete the Attestation page.

    http://emersehost:port/emerse/login.html

  • Once you are at the EMERSE page where you could enter terms for a search, enter the following URL into the browser (not the EMERSE search box) and press return:

    http://emersehost:port/emerse/springmvc/admin/patientIndex
Make sure the letter I in the word index is capitalized in the URL above.

You should see a screen that says, "Patient Indexing started". Visiting this page should invoke a process that copies the Patient table from the database over to the Solr patient index. This page will not provide feedback about when it is complete, so then visit this URL to see when it is done:

http://emersehost:port/solr/#/patient

This URL shows the status of the patient index. You can find it by looking for the Last Modified time under Statistics. It won’t say 'complete', but it should report a very recent time frame, such as within the last few minutes. If not, wait until it is complete. Refresh the page from time to time to see if the Last Modified status has changed.

Solr Patient Index page
Figure 1. Check the Last Modified date of the patient index.

  • Once the patient index has been copied, do the same for the patient-slave index. Visit the URL:

    http://emersehost:port/emerse/springmvc/admin/patientIndex/optimize

This will copy the patient index over the the patient-slave index. It should say "Patient Index Optimization started".

  • Similar to the patient index, visit the following page to see the status on when it is done copying:

    http://emersehost:port/solr/#/patient-slave
Solr Patient Index page
Figure 2. Check the Last Modified date of the patient-slave index.

Note that the replication from the patient index to patient-slave index is supposed to occur every minute, so the above task to replicate from patient to patient-slave may not be needed as long as you can wait a minute for the process to occur by itself. If the updating isn’t occurring automatically every minute, see more details about the Patient Slave Replication Setup, below, or check the configuration details as outlined in the Configuration Guide.

Patient Slave Replication Setup

If you have trouble rebuilding or updating the patient indexes (see above), then it is worth checking to make sure that the patient and patient-slave indexes are set up correctly in terms of replication. One place to check is on the main Solr home page:

http://localhost:8983/solr/#/patient-slave
Patient Slave Index incorrectly configured
Figure 3. To check if the patient-slave index is properly configured, visit the Solr home page, then select the patient-slave core. If you see that it says "Replication (Master)" then the patient-slave index is not properly set up.

If the setup is not correct, one place to check for problems is in the solrconfig.xml file in the patient-slave core to make sure that the replication from patient to patient-slave is set up correctly.

<requestHandler name="/replication" class="solr.ReplicationHandler" startup="lazy">
    <lst name="slave">
      <str name="masterUrl">http://localhost:8983/solr/patient/replication</str>
      <str name="pollInterval">00:01:00</str>
    </lst>
  </requestHandler>
Patient Slave Index incorrectly configured
Figure 4. If replication for the patient-slave index is set up correctly, you should see that it says "Replication (Slave)"

Diagnostic Checklist

EMERSE provides a high level 'diagnostic page' (diagnostics.html) that checks to make sure various components of EMERSE are available and responsive, including the database, ActiVQ, and Solr. This may be most helpful when working on an installation of EMERSE. Details about how to access this page can be found in the Installation Guide.

Demographic Charts not Loading

If the charts for demographics do not display, or display incorrectly, after running a search across All Patients, there may be a problem with the mapping of the demographics. EMERSE requires demographics to be coded and they should match the contents of the look-up tables within the relational database. If they don’t match, an error will occur and the charts may not get displayed properly.

Another reason they might not load is if the patients in the relational database do not match the patients in the Solr patient index, so this is also worth checking into.

Updates to the Project.Properties File

The project.properties file is where the majority of configuration options are available for EMERSE. As the software gets updated the properties in this file are likely to change over time, especially as new properties are added. This file is another good place to check for discrepancies if there are errors running EMERSE.

User Reports Some Buttons Grayed Out/Not Accessible

If a user reports that some buttons are grayed out or not accessible, it may be because their roles/privileges were set incorrectly. This can be checked and modified from within the EMERSE Admin app (see: Administrator Guide). Additional details about roles and privileges can be also found in the Administrator Guide.