Administrator Guide

This guide covers topics relevant to EMERSE system administrators.

Basic system administrator functions can be found on the admin page (which is actually a separate application). The administrator page provides mechanisms for adding users, making them active/inactive, managing system-wide synonyms, managing roles/privileges, and more. The Admin page page also contains a way to view some of the EMERSE log files, which can be useful for troubleshooting, especially during initial installation. More details about this feature can be found in the Troubleshooting Guide.

The admin page can be accessed after logging into EMERSE and completing the attestation. Then, in the main EMERSE application it can be accessed via the EMERSE menu in the upper right portion of the screen. The Admin option will only appear in the drop down menu if the logged in user has admin privileges.

The admin page can also be accessed directly at the URL below as long as the user has admin privileges.

EMERSE provides for the capability to have an announcement displayed to users after logging in and completing the Attestation page. This may be helpful if there is a need to communicate something to all users, such as a planned system shutdown, or an announcement about an updgrade. More than one announcement can be shown, and each announcement will be shown to every user until either the user clicks on the Don’t Show Again button, the administrator clears the announcement, or the announcement "expires". If more than one announcement is entered for users, each will be shown in succession (not all together on the same announcement window).

This feature is now easily accessible in the Admin app under the Alerts section. You can add the text of the alert, as well as the start and stop dates for when the alert should be shown. Basic HTML (line breaks, links, etc) can be included and should be interpreted correctly when displayed to the user.

There may be rare cases in which a user’s User ID has to be changed (for example, someone’s last name has changed leading to a change in the User ID). Such changes can be made from the Administrator page.

Users can be authenticated via two mechanisms:

This can be set, and later changed, on the Administrator page by choosing either Active or Inactive for the switch that allows for "External Authentication (Ldap, etc)".

This result is stored in the EXTERNAL_AUTH column (1, 0) in the LOGIN_ACCOUNT table, and it tells the application what authentication to prefer.

When EMERSE is configured to use LDAP as an authentication source (see the Configuration Guide for how to do this), it is still possible that a user can login if their password matches the encrypted credentials in the password field of the LOGIN_ACCOUNT table. If the EXTERNAL_AUTH flag is set to true (EXTERNAL_AUTH=1), however, the application won’t try to match the user’s credentials against the LOGIN_ACCOUNT table. In other words, when this flag is set to 1, the password field has no impact for the user, and only the external authentication mechanism is used.

The visibility/accessibility of some user interface elements or features within EMERSE are controlled directly by a user’s set of privileges. Privileges are determined mainly through the users’ roles that are set up in the USER_ROLES table. Each role is mapped system-wide to a set of privileges. The ROLE_PRIVILEGES table contains a full list of possible actions/components/features that are assigned to a specific role in the application. These roles and privileges can now be managed through the administrator app, without the need to modify the underlying database tables (see the section on "Role page", below).

Currently EMERSE has only one role where this is implemented, the “DEFAULT_USER” role. The ROLE_PRIVILEGE table contains a mapping of roles to privileges. For example, the "DEFAULT_USER" role has privileges:

An example of what can be done using this primary "DEFAULT_USER" role is that one could disable all users’ access (assuming no other roles have the same privilege) to exporting patient lists by removing EXPORT_PT_LIST privilege from the ROLE_PRIVILEGE table.

Privileges can also be granted to or revoked from a specific user by adding rows to the PRIVILEGE_EXCEPTIONS table. The ADD_PRIVILEGE column determines whether the privilege will be granted to the user (Y), or revoked from the user (N), essentially acting as a blacklist and whitelist. This table is consulted first, and only if there is no entry for the specific user and privilege will the roles be considered. So, if a privilege is revoked here, the user will not have it, even if they have a role that grants it to them.

The default configuration for the EMERSE system is that the DEFAULT_USER has all privileges except access to the admin app and the server API. If these standard privileges are not desirable for the typical user of EMERSE, then one can simply remove the undesired privileges from the ROLE_PRIVILEGES table.

Alternately, you can create a new role by adding a row to the USER_ROLE_DESC table, and associate the wanted privileges with that role by adding rows to the ROLE_PRIVILEGES table. You can then assign users that role in the admin app. To do so, navigate to the users tab, find the user by name in the table, and click edit. This will bring you to a page that has a few checkboxes whose text matches the description of the role in the USER_ROLE_DESC table. Select the checkboxes for the roles you want the user to have. You can also add or remove roles to users in the database directly by changing the USER_ROLES table.

EMERSE supports a type of query expansion we call Synonyms. These are system-suggested terms/phrases that help users conduct a more thorough search. Synonyms can include alternative phrasings, acronyms, abbreviations, misspellings, stemming, related concepts, and more. These system-wide term suggestions can be leveraged by users but can only be updated by an administrator. There is no need to make your own Synonyms dataset since we provide several that have been formatted specifically for EMERSE, including Enesmbl gene names and associated diseases, the Human Phenotype Ontology, and others. Details can be found on the EMERSE website. You can download these datasets from the project-emerse.org website and and then upload them into the EMESRSE application using the EMERSE Admin app and by following the directions below. The sections below also describe how you can make your own Synonyms file, which may be useful if you want to add localized suggestions, or add additional data sources.

In addition to the sytem-wide Synonyms users can make their own collection of terms using the Saved Terms feature (previously called a Term Bundle), and can incorporate system-suggested Synonyms into their Bundles. User-created terms can be made available to other users through the Saved Terms sharing feature but they will not automatically become a part of the system-suggested Synonyms unless they are added by an administrator.

The Log tab in the EMERSE admin page is a good place to look if you are running into problems. It will show any recent errors that are appearing in the system logs (which are different from the audit logs stored in the database). More details about troubleshooting can be found in the Troubleshooting Guide.

The System tab in the admin app provides a feature to help synchronize components of the system. In general this should not be needed since synchronization automatically occurs once per night. However, when installing the system or troubleshooting it may be useful to force these events to occur immediately so that changes can be verified. To invoke this, simply click on the Synchronize button. Some of these actions may take time, though.

The Synchronize action will:

Additional details about how to check the progress of these synchronization steps can be found in the Troubleshooting Guide.

The Caches page under the System tab allows you to force EMERSE to refresh its caches of certain database tables. This is normally done periodically on a "cron job" (see the Configuration Guide), however, during installation, it may be helpful to force a refresh if you made significant changes to the database, but don’t want to restart EMERSE.

The Heatmap (now called the Overview within the application) Statistics page under the System tab contains some statistics about the performance of EMERSE to run queries from the "Overview Page" in the EMERSE application. These can be especially slow to run since the queries can be complex and numerous, in addition to the fact that it’s one of the most used parts of EMERSE.

The statistics are split up into a few sections. The only statistics collected are simple minimum, maximum, and average. Some statistics are point-in-time snapshots, but most are cumulative, and can be reset to zero with the "Reset Stats" button. The "Reload Stats" button allows you to update the statistics displayed; they are not live. Reloading the whole page would do the same, but the button is much faster.

The EMERSE team tries to keep up with the latest versions of software components, as this is seen as a good approach to ensure security. While some components are installed by each site (e.g., Tomcat, Solr), other components come pre-installed with the EMERSE distribution. One way to check for the versions of these additional components is shown below for Spring and Hibernate:

Note that the specific version numbers of the war file may change based on the current version of the EMERSE distribution.

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.

EMERSE maintains persistent audit logs of user activities, including logins, attestations (reasons for use with each session), patients/notes viewed, and search terms, among other actions. While reports are not currently built into the interface, you can access these logs via the database. We have several prebuilt SQL queries that can be found in the Reporting and Auditing Guide.

Each user’s set of search terms is captured in the audit logs, and these are the actual terms used. In other words, the terms are not referenced back to original sources (such as the Synonyms suggestions), which means that updating or changing the system-wide Synonyms will not affect the ability to retrieve or interpret existing search terms in the audit logs.

Some items are not captured in the audit logs, including any comments or tags (used for annotating the patients lists) affiliated with a Saved Patient List.