...
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.
Technologies used to create the admin pages will be mainly JSP and JQuery in correspondence with the Spring MVC framework.
Mentor: Roger Friedman (Unlicensed)
...
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
TBD
Administration Pages
TBD
Work on OpenMRS core / REST module
TBD
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.
...
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.
...
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.
...
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 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 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
...