Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents


This is a simple module, which can be used to create and customise forms to manage patients' laboratory test orders, samples an-d and results.


The module provides RESTful API and legacy OpenMRS interface, it provides:

  1. Administrative forms to create new Lab tests and define their set of results.
  2. Separate tab on patient's dashboard to create Lab test orders
  3. Collect and manage specimen samples (if required) to process
  4. Enter test results
  5. Attach scanned/documented reference files for test results

Module Structure

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.


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/webapp/... contains the JSP files and related resources

Data Model

The LabTestType maps to commonlabtest_type, where all lab test types are stored, for example CD4 test, CBC test, Ultrasound test.


The best documentation for developers is test cases. Check out the examples in unit tests for complete details. (smile)


The module requires OpenMRS version 2.0.x or higher and Legacy UI module as prerequisite.


  • Privileges: Add/Edit/Delete/View CommonLabTest Metadata, CommonLabTest Orders and CommonLabTest results
  • A concept (if one does not exist) named UNKNOWN LAB TEST TYPE (uuid b095450e-9ad0-11e8-844c-448a5b471032)
  • Default LabTestType: Unknown Test Type (uuid ee9b140e-9a29-11e8-a296-40b034c3cfee)

Global Properties

Following are the global properties that are created on installing the module:


titleGlobal Properties

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

  • how to configure metadata
  • basic workflow of module from requesting an order to filling test results
  • sample management  

Configuring Metadata

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 Attribute Types as explained in detail below.

Lab Test Types

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 pageeach 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 Requires Specimen 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

Lab Test Attribute types basically serve as the questions that constitute the details of a Lab Test Result. 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. 


  1. Lab Test Type: Attribute Types are created against Lab Tests therefore, this field refers to the test type to which the new attribute type belongs. 
  2. Name: It holds the name assigned to the Attribute type.
  3. Description: Any additional information/description is filled in this field.
  4. Multiset Name: If the question asked in the test can have multiple answers, then for each answer an attribute type is created. But all of these answer Attribute Types should have same Multiset Name. Please see the example below. 

  5. Group Name: Group name refers to group of questions listed under a single heading. Like in above example, Kanamycin contains a group of questions (Wild Type Band Failed and Mutation Band Developed). Therefore, they are listed under single heading Kanamycin.
  6. Min Occurs: It refers to the minimum occurrence of an attribute type in a test result.
  7. Max Occurs:It refers to the maximum occurrence of an attribute type in a test result.
  8. Sort Weight: It refers to the sequence number in which attribute types (question) will appear in test result form.
  9. Data Type: It refers to the datatype assigned to attribute type. These are the supported data types: Boolean, Long Free Text, Float, Concept, Regex Validated Text, Free Text, Date. Concept datatype is assigned to attribute types that are closed ended questions for example, question for confirmation of cough has Yes, No, Unknown, Refused options as answers. Therefore, such attribute type will be created with Datatype Concept.
  10. Datatype Configuration: In case of an attribute type with Concept datatype, concept ID should be mentioned in the datatype configuration field. In case of Text, Regex Validated Text, Float values, DataType configuration can be used to mention Length or Regex or Range. Please see example below.  
  11. Hint: It is used to mentioned any additional info. For example, if only numeric value is allowed in float datatype then hint can be filled as "Numeric value with max length 2". It will appear with the question on the Test Result form.
  12. Preferred Handler: Should be kept as Default.
  13. Handler Configuration: Should be left as blank.


On installing module, there is a new tab Lab Tests created on patient dashboard. In Lab Tests tab, there are two options available (Add Test OrderAdd Test Request).


Following form can be used for generating multiple Test Order requests. It displays all Test Types in their respective Test Groups which are initially closed sections. On clicking the plus icon, the section opens up and on selecting the corresponding checkbox, Lab Reference number is filled with auto generated timestamp.

Sample Management

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. 


titleVoiding Data
  • If a Lab Test Type is deleted, its referred data like Lab Test Orders and Attribute Types are linked to UNKNOWN Test Type.
  • If a Lab Test Type is deleted (purged), its referred data like Lab Test Orders are also deleted (purged). It can be done by calling method deleteLabTestType(LabTestType labTestType, boolean cascade) and passing cascade as TRUE.
  • If a Lab Test Attribute Type is deleted (purged), all attributes that were saved against this Attribute Type are also purged.
  • If a Lab Test is voided, its subsequent linked data like Test Samples and Test Results (attributes) are also voided.
  • If a Lab Result is voided completely (all attributes), then the sample linked to this result is changed back from PROCESSED to COLLECTED status again.


Source Code


This module was developed by Owais Hussain Tahira Niazi Muhammad Ahmed Memon and  Shujaat Ali from Interactive Health Solutions.