hmis-saas/readme.md

OpenMRS Service Integration

This project integrates with OpenMRS to manage patient records, visits, location hierarchy, and clinical data. The service leverages OpenMRS's robust API to ensure seamless interoperability between our application and OpenMRS.

Table of Contents

1. Overview
2. Patient Records Management
3. Visit Management
4. Location Hierarchy Management
5. Clinical Data Management
6. Environment Configuration
7. Helper Code

Overview

The integration with OpenMRS allows our application to:

• Check for existing patients in the OpenMRS system.
• Register new patients and update existing patient records.
• Manage patient visits.
• Handle a hierarchical location structure to support multiple hospitals.
• Store and manage clinical data, such as medical concepts.

We are using OpenMRS version 2.5 without any modifications. We are utilizing the core modules and the REST API to interact with the OpenMRS system. Below is a table listing the modules and their versions that we are using:

Module Name	Version	Author
Registration Core Module	1.12.0	OpenMRS Developers
ID Generation	4.10.0	Partners In Health
Event Module	2.10.0	OpenMRS
Provider Management Module	2.14.0	Mark Goodrich
Visit Management Module	1.0	OpenMRS
FHIR2	1.3.0	OpenMRS FHIR Squad
App Framework Module	2.17.0	djazayeri
Open Web Apps Module	1.13.0	Saptarshi, Namrata, Sandeep
Admin UI Module	1.6.0	Ujjwal Arora
UI Commons Module	2.24.0	OpenMRS
App UI Module	1.17.0	OpenMRS
Rest Web Services OMOD	2.41.0.756cb3	OpenMRS
OpenMRS UI Framework	3.24.0	OpenMRS
Legacy UI Module	1.16.0	Tharunya
Bed Management Module	5.13.0	Thoughtworks
UI Library Module	2.0.7	djazayeri

Patient Records Management

Check Existing Patient

We can check if a patient already exists in the OpenMRS system using their identifier (patientId). This helps avoid duplicate records.

const existingPatient = await openmrsService.checkExistingPatient(patientId);

Register New Patient

If a patient does not exist, we register them in the OpenMRS system.

const newPatient = await openmrsService.registerPatient({
  name: "John Doe",
  patientId: "12345",
  locationId: "1",
  gender: "male",
  birthdate: new Date("1990-01-01"),
  address1: "123 Main St",
  cityVillage: "Dhaka",
  postalCode: "1234",
  attributes: [{ attributeType: "Phone Number", value: "0123456789" }],
});

Update Patient

If the patient already exists, we update their details.

const updatedPatient = await openmrsService.updatePatient({
  name: "John Doe",
  openmrsId: existingPatient.results[0].uuid,
  patientId: "12345",
  locationId: "1",
  gender: "male",
  birthdate: new Date("1990-01-01"),
  address1: "123 Main St",
  cityVillage: "Dhaka",
  postalCode: "1234",
  attributes: [{ attributeType: "Phone Number", value: "0123456789" }],
});

Registration Encounter triggered via API

Visit Management

We manage patient visits by creating and retrieving visit types and visits.

Create Visit Type

const visitType = await openmrsService.createVisitType(
  "General Visit",
  "A general check-up visit."
);

Create Visit

const visit = await openmrsService.createVisit(
  "patient-uuid",
  "visit-type-uuid",
  "2023-06-01T08:00:00Z",
  "Routine check-up",
  "location-uuid"
);

Location Hierarchy Management

OpenMRS supports a hierarchical location structure which allows us to manage multiple hospitals and their sub-locations.

Create Location

Locations represent different hospitals or units within hospitals.

const location = await openmrsService.createLocation(
  "Main Hospital",
  "456 Another St"
);

Check Existing Location

Before creating a new location, we check if it already exists.

const existingLocation = await openmrsService.checkExistingLocation(
  "Main Hospital"
);

Location Hierarchy

The location hierarchy is managed in a way that allows us to link sub-locations (like departments or wards) to parent locations (main hospital buildings). This hierarchical structure facilitates the management of multiple hospitals within a single OpenMRS instance.

Clinical Data Management [Under Development]

OpenMRS is used to store various types of clinical data, including medical concepts.

Medical Concepts

Medical concepts are used to standardize and manage clinical data. They represent diagnoses, procedures, and other clinical information.

Create Medical Concept

We interact with the OpenMRS API to create and manage medical concepts. (Under Developent)

Helper Code

OpenMRS Client Helper

The openmrs.py script handles the communication with the OpenMRS API to update location information and establish parent-child relationships among locations.

openmrs.py

import json
import requests

base_url = "http://***.***.***.**:****/openmrs/ws/rest/v1"
auth = ("****", "****")

with open("seeded-openmrs.json", "r") as json_file:
    data_dict = json.load(json_file)

def update_location(location_id, parentLocation):
    url = f"{base_url}/location/{location_id}"
    headers = {
        "Content-Type": "application/json",
        "Access-Control-Allow-Origin": "*"
    }
    body = {
        "parentLocation": parentLocation
    }
    try:
        response = requests.post(url, json=body, headers=headers, auth=auth)
        if response.status_code == 200:
            return True
        else:
            print(f"Failed to update location with ID {location_id}")
            return False
    except requests.exceptions.RequestException as e:
        print("Request Exception:", e)
        return False

for key, values in data_dict.items():
    if not data_dict[key].get("parentLocationId"):
        continue
    print("Updating location with ID: ", data_dict[key]["openmrsId"], "with parent location: ", data_dict[data_dict[key]["parentLocationId"]]["openmrsId"])
    update_location(data_dict[key]["openmrsId"], data_dict[data_dict[key]["parentLocationId"]]["openmrsId"])

Parent-Child Location Helper

The parent-child.py script defines the LocationHierarchy class, which provides methods for creating new locations and checking for existing locations, thereby helping to build and manage the hierarchical structure of locations.

parent-child.py

from openmrs import OpenMRSClient

class LocationHierarchy:
    def __init__(self, client: OpenMRSClient):
        self.client = client

    def create_location(self, name: str, address: str):
        return self.client.create_location(name, address)

    def check_existing_location(self, name: str):
        return self.client.check_existing_location(name)

Building the Location Hierarchy

1. Creating Locations: The LocationHierarchy class in parent-child.py is used to create new locations by calling the create_location method. This method interacts with the OpenMRS API to register the location in the system.
2. Updating Locations: The update_location function in openmrs.py is used to update an existing location's information and set its parent location. This establishes the parent-child relationship necessary for the hierarchical structure.
3. Establishing Parent-Child Relationships: The openmrs.py script reads location data from a JSON file (seeded-openmrs.json) which contains information about each location and its parent. It then iterates over this data to update each location with its corresponding parent location using the update_location function.