Lab Administration Pages: GSoC 2012

Project description

This project's aim is to create a UI for administering the Laboratory module. This involves designing and implementing a module installation process, that will integrate the module with an existing OpenMRS installation, as well as the creation of the actual administration pages. The admin pages will be responsible to manage all of the meta data that is required to operate the Lab module. 

Mentor: Roger Friedman (Unlicensed)

Student: Martin Losse (Unlicensed)

Blog: http://summon-gsoc.blogspot.de/

Roadmap/Timeline: -> GDoc

Codebase: OpenMRS SVN - JSSLab module

1. Project Summary

This project was worked on in the period of GSoC 2012 from May 21 until August 20. The codebase that was created in the period can be accessed from the SVN directory referenced above.

1.1 Technologies Used

The software created in the scope of this GSoC project is an OpenMRS module. OpenMRS is a medical record system that uses Java and the Spring MVC framework at its core. The module created extends the web frontend of OpenMRS by additional administration pages and as such is exposed to the core technologies and additional ones related to web development. At the heart these are JSP pages and in the case of this module a heavy dependency on the Javascript framework jQuery.

Most data for this module transferred between the core application and the web frontend is sent via asynchronous XmlHttpRequests through the OpenMRS REST API. Relevant technologies, concepts and notations here are REST, JSON and Javascript/jQuery.

The build process and dependency management is performed using Apache Maven.

1.2 Completed Tasks and Future Work

Completed Tasks

Installation

The project started out as a module built for OpenMRS 1.8. An early and important concern was to design and implement an extensible semi-automatic installation process. It was designed to automatically install module specific database data using Liquibase. That way a migration to a newer OpenMRS version could be achieved by adding new ChangeSets that will transform the existing module specific tables to match the requirements for the new version.
The manual part of the installation process involved  

Migration from OpenMRS 1.8 to 1.9

The module has been adapted to work with OpenMRS 1.9. A branch was created for the latest build working with OpenMRS 1.8 and is planned to be maintained alongside the OpenMRS 1.9 compatible trunk. Since OpenMRS 1.9 is aiming for support of different databases, special attention has been paid to creating and/or editing existing changesets such that cross-DB compatibility is not broken by JSSLab module.

Administration Pages

The Initial Setup page has been completed (as to the requirements known to date).

The Instruments and Supplies page has been completed.

The Settings page has been completed. Minor issues remain.

The Catalog page has been worked on. Nearly all form elements are present, some are missing functionality. Most save operations are not yet implemented.

REST Resources

The REST resources added with the JSSLab module have been largely untested before the start of the GSoC project. In the course of the project many resources have received fixes and additions to solve problems that were identified with them. Several custom queries were written to provide a way to access more specific queries in a REST-like manner, that would not be accessible otherwise.

Work on OpenMRS core / REST module

While working on the JSSLab module a number of issues and missing features were discovered in the OpenMRS core and in the REST module and were reported as Tickets in the issue tracker for OpenMRS. Some work that was important for this module's functionality was worked on (RESTWS-272), other issues were merely reported to make the community aware of them.

Future Work

Administration Pages

Out of a total of 6 administration pages in the module, 5 were initially planned to be completed in the scope of this GSoC project. Due to time limitations 3 out of 5 pages were completed and a 4th page has been created but is not fully functional.

The Reports page was beyond the scope of the project and will have to be worked on in the future.

The Specimen Templates page has only been created as a stub that does not contain any functionality and could not be worked on due to time limitations.

The Catalog page contains nearly all elements that are required for its operation. Some of these are not fully functional and a lot of form data can be edited but not yet be saved.

Validation

Validation has not been built into the forms on the client side and will result in failing save operations in the persistence layer. Appropriate feedback is missing.

Unit Tests

Many changes, enhancement and bug fixes have been performed in the module's own REST resources. A lot of these are not backed by unit tests, that will need to be added in future to ascertain the proper functionality of the resources.

Manual Tests / Code Reviews

A thorough manual testing of all admin pages and REST resources will be required when the module is ready for release. Code reviews should be performed to uncover problems with coding style and/or identify possible performance bottlenecks.

2. Module Functionality

The JSSLab admin module aims to allow extensive configuration of metadata related to the JSS Lab. Any data required for the JSSLab frontend forms to work will be set up here. The following sections will outline the installation process and describe the options available on each page of the module.

2.1 Module Installation

Being OpenMRS module the first concern is the installation on an OpenMRS instance. 

As there are significant changes between the OpenMRS versions that impact the functionality of the module, the JSSLab admin module is also offered in different version, depending on the OpenMRS version that is being used. The minimum OpenMRS version that is supported is OpenMRS 1.8. For better identification of which module version is required, the module version is locked to the OpenMRS version. Any version of the JSSLab admin module starting with 1.8 will be compatible with the latest OpenMRS 1.8 release, whereas a version of 1.9.* on the module will indicate compatibility with OpenMRS 1.9.

The module is packaged as an omod file, that can be added to an OpenMRS instance the way a module would normally be added (either via the admin interface or by dropping the omod into the appropriate folder). 

2.1.1 New installation

When it is first installed JSSLab admin module will update the OpenMRS database, creating new tables that are specific to the module. In addition to that, default metadata, that is required for the module's operation, is added to existing OpenMRS tables. 

As the user first tries to access any of the module's pages, they will be redirected to the initial setup page. This page allows the user to change the default settings for the central global properties needed to operate the module and offers the option to install sample data to better showcase the capabilities of the module. Once the necessary changes have been made, the user will have to click on Finish Setup to be redirected to the page they were planning to access. If the user desires to visit the setup page again it can be selected from the top menu when in the module's administration.

2.1.2 Updating JSSLab admin module

As maintenance releases to the module are released or the user chooses to migrate to a newer OpenMRS version it will become necessary to update the JSSLab admin module running on the OpenMRS instance. The update procedure, like the first installation is also OpenMRS standard. The user can choose to either upload the new version to the system or drop it in the appropriate place in the file system. As the application context is reloaded, the new module version will automatically make any necessary adjustments to the database tables. In case manual settings have to be made, the user will again be presented with the initial setup page if he tries to access any of the module's pages.

2.2 JSSLab Administration Pages

The JSSLab admin module extends the OpenMRS administration by a new section called JSSLab. In this section there are 5 (+1) pages available to work with, that will be described throughout this section.

2.2.1 Settings

At the top of the Settings page the user can choose to edit the Locations that exist in the system. They can add new Locations, change their names, address and mark them as referral or managed Laboraties.

If a Location is marked as referral, it means, that it has a Laboratory and Lab Orders can be sent to it. If it is marked as managed it means that it is the preferred (and usually local) Laboratory. There can be only one managed Location at any one time.

Additionally, the settings page offers configuration capabilities for all JSSLab specific Global Properties. Their values can either be plain Strings or references to an object of a certain class. In the latter case available options are offered as an autocompletion field below the textbox being edited.

Finally, the Settings page can be used to manage so called Code Lists. These are lists of Concepts that resemble certain categories. For example the possible reasons to reject a test are grouped in the code list "REJECT REASON".

The screenshots below illustrate what the page looks like.

2.2.2 Catalog

The Catalog page has a core role in managing the JSSLab metadata. On it the user can create and edit Investigations and the associated Tests. Each lab that was previously marked as referral or managed on the Settings page can now be accessed from the Laboratory-labeled dropdown field that can be seen in the screenshot below.

The list of Investigations shown in the table below will adjust according to the currently selected location. The right side allows the user to change all details of the Investigation, except for the Tests performed for it. 

Due to the complexity of the Test metadata a separate pair of panels was created for the management of it. The screenshot below shows those panels. The tests being displayed in the list on the left again depend on the currently selected investigation in the top left panel.

2.2.3 Templates

The Templates page has not yet been implemented. It will allow the user to create hiearchies of Specimen Templates that will describe in what way and order Specimens will be handle to complete a particular investigation.

2.2.4 Instruments and Supplies

This page permits the user to edit and create lab instruments and supply items to resemble what is available and what parameters like condition and date of purchase are. The screenshot below shows and instrument being edited.

2.2.5 Reports

The Reports page has not yet been implemented, but also was not in the scope of the GSoC project. It will allow the management of metadata

2.2.6 Initial Setup

This page is loaded if the user tries to access any of the module's pages before the initial setup has been completed. This will happen usually after the module is first installed. It may also happen after a module update, if there are changes that require user input to complete.

The Initial Setup page also allows the user to install sample data, which is primarily relevant to showcase the module's functionality.

3. Design

This chapter contains all relevant information on the design of the JSSLab admin module. There are three domains to be concerned here.

The first is the installation process of the module. 

The other is the actual administration part on the administration pages.

3.1 Installation Process

The installation process describes the set of actions that have to be performed when the module is loaded (newly installed, updated or restarted).
These slides visualise the process as it is currently planned to be implemented.

• The database table shells required for operation of the module need to be checked for presence, altered if they are outdated or created if they do not yet exist.
• Global properties need to be created and set up
• Default Report Definitions (xml files) are installed in a default directory (filesystem), another directory will be used for custom reports for easy distinguishing
• If the module is installed for the first time the user will be given several choices
  
  • whether they want to install base data
  • whether they want to install sample data
• If the module is updated
  
  • whether they want to update the base data
  • whether they want to install new sample data (old sample data will be removed, if any)

Database setup operations will be performed using Liquibase

• the default liquibase.xml will be automatically run by OpenMRS during the module installation and create all table shells for JSSLab
• liquibase-sample.xml and liquibase-basedata.xml will be called on demand if the user chooses to have the data installed.

3.2 Admin pages

Mock-ups of the admin pages are available here

The admin section is currently planned to consist of 5 pages. In general the admin section allows administrators to configure all the meta data that drives the JSSLab module. The functionality is as follows:

• Settings
  
  • Selection of one particular laboratory that is to be considered as "managed" within the system
  • Selection of other laboratories that should be available for the creation of Lab Orders
  • Creation of new laboratories
  • (Creation of Global Properties)
  • (Modification of code lists)
• Catalog
  
  • Configure Investigations (Panels) that can be performed by a specific laboratory
  • Configure Test Results for Investigations
• Templates
  
  • Configure Templates that are going to be used in Investigations
  • Describe/update Templates that have been used in Investigations prior to being configured on this page
• Instruments & Supplies
  
  • Configuration of the instruments and supply items, that should be available for selection/autocomplete in forms and generally available to Lab module users
• Reports
  
  • Management of report definitions
  • Download of existing definitions
  • Upload of custom definitions

Jira Tickets