236 lines
8.6 KiB
Markdown
236 lines
8.6 KiB
Markdown
# 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)
|