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](#overview)
2. [Patient Records Management](#patient-records-management)
3. [Visit Management](#visit-management)
4. [Location Hierarchy Management](#location-hierarchy-management)
5. [Clinical Data Management](#clinical-data-management)
6. [Environment Configuration](#environment-configuration)
7. [Helper Code](#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.

```typescript
const existingPatient = await openmrsService.checkExistingPatient(patientId);
```

### Register New Patient

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

```typescript
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.

```typescript
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

![Patient Registration](./4.png)

## Visit Management

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

### Create Visit Type

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

### Create Visit

```typescript
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.

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

### Check Existing Location

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

```typescript
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`

```python
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`

```python
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.

![Location Hierarchy](./1.png)
![Location Hierarchy](./2.png)