This is a simple module, which can be used to create and customise forms to manage patients' laboratory test orders, samples and results.
The module provides RESTful API and legacy OpenMRS interface, it provides:
The module is structured according to OpenMRS conventions found here.
src/main/java/org.openmrs.module.commonlabtest.api.impl/CommonLabTestServiceImpl implements CommonLabTestService which extends OpenmrsService.
The unit tests can be found in
src/test/resources/CommonLabTestService-initialData.xml contains the test data
src/main/java/org.openmrs.module.commonlabtest.web.controller/... contains all Controllers for web app
src/main/java/org.openmrs.module.commonlabtest.web.resource/... contains all REST controllers
src/main/webapp/... contains the JSP files and related resources
The LabTestType maps to commonlabtest_type, where all lab test types are stored, for example CD4 test, CBC test, Ultrasound test.
LabTestAttributeType maps to commonlabtest_attribute_type; against each LabTestType object a set of LabTestAttributeType is meant to be created, each representing an observation which will be captured when entering results. For example, for CBC test, some LabTestAttributeType can be RBC count, WBC count, Haemoglobin and Platelets.
A LabTest object maps to commonlabtest_test extends OpenMRS object, each patient lab test is referred by this object. This object contains a mandatory Order object, which is abstract OpenMRS object used for Lab tests and Drug orders.
LabTestSample object, which maps to commonlabtest_sample table, contains specimen samples (if the associated LabTestType requires a sample to process a test).
Test results for LabTest object are stored in LabTestAttribute (extends BaseAttribute abstract class) objects, which map to commonlabtest_attribute. An important thing to note here is that an attribute's value might be open-text, numeric, concept, drug, or even a location. The value_reference column contains the reference of the actual value. The Service API returns the associated object, while the RESTful API returns the reference value only.
The best documentation for developers is test cases. Check out the examples in unit tests for complete details.
The module requires OpenMRS version 2.0.x or higher and Legacy UI module as prerequisite.
On installing the module, some data is created in the database:
Following are the global properties that are created on installing the module:
commonlabtest.fileExtensions refers to the types of files that can be saved as attachments.
commonlabtest.fileDirectory refers to the directory that holds the uploaded attachments (located in OpenMRS application directory as .../complex_obs/commonLabTestFiles).
commonlabtest.specimenTypeConceptUuid = 162476AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA refers to the different types of samples, for example plasma etc.
commonlabtest.specimenSiteConceptUuid = 159959AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA refers to the source of collected sample, for example pulmonary tissue etc.
commonlabtest.testunitsConceptUuid = 5db4f53e-6218-4ae0-ae4e-5e0343b5d30 refers to the units in which sample can be quantified.
Please note if the global properties are not set up then errors may be encountered while using module. Therefore, setting up global properties is a required step (ideally should be automatically done during installation of module).
This section describes the basic workflow of module from requesting an order to filling test results.
Apart from configuring global properties, there are two types of metadata objects that should be created before using Common Lab Module. Those are Lab Test Types and Lab Test Attributes as explained in detail below.
Lab Test Types refer to the type of tests for which the orders can be requested, for example CXR, AFB Smear etc. On main Administration page under the heading of Common Lab Test, Manage Test Types redirects to the page that manages information related to all the test types.
On Add Test Type page, each Test Type is linked with a reference concept for example, CXR Test type should have a reference concept object (concept name does not necessarily need to match, it can be CHEST X-RAY or CXR etc.). Test Group refers to the the group to which this test belongs. Group is an enum list containing test groups like Serology, Cardiology, Ophthalmology, Bacteriology, Biochemistry, Blood_Bank, Cytology, Hematology, Immunology, Microbiology, Radiology, Sonology, Urinalysis and Other. Last question denotes that test type either requires or doesn't require specimen to produce results. Manage Test types is updated after test type is created successfully.
Lab Test Attribute types basically serve as the questions that constitute the details of a Lab Test. Values against these Test Attribute Types are saved while submitting Test Results. These attribute types can be created from the option Manage Attribute Types on Administration page.
On Add Attribute Type page, there are multiple fields that are described below:
On installing the module, there is a new tab Lab Tests created on patient dashboard. In Lab Tests tab, there are two options available (Add Test Order & Add Test Request).
Add Test Order refers to single Test order request whereas Add Test Request can be used for creating multiple Test order requests at a time. Additionally, in this tab there is a list of Test Orders requested for that patient. Add Test Order directs to the following page.
Above screenshot represents the form to create Test Orders.
After the test order is successfully created, the List Test Order is updated in Lab Tests tab as it can be seen below.
The list of Test Order contains following options:
On Manage Lab Test Sample page, there is a link to Add Test Sample page. It has four required fields Specimen Type, Specimen Site, Sample Identifier and Collection Date. Like Lab Reference Number, sample identifier is an auto-generated time stamp which can be edited and replaced with the actual Sample ID, if available.
After the test sample is successfully added, the list on the Manage Test Sample page is updated and the newly entered sample is set to COLLECTED status. Sample status is an enum with four possibilities i.e. COLLECTED, ACCEPTED, REJECTED, PROCESSED. Please note that there is an option to reject sample as well in case if sample is contaminated or expired. REJECTED samples are not acceptable for conducting tests, therefore in case of a rejected sample, a new sample has to be submitted. Results can be entered only after sample status is changed to ACCEPTED, and after successful submission of test results. sample status changes to PROCESSED status.