Digital-Square-Tanzania/ucs-hfr-integration-service
Domain:
healthcaredigital infrastructureRecord type:
software
Creator:
Dig
Host:
UCS HFR integration service: receives HFR facility updates, refreshes location hierarchies, creates/updates OpenMRS locations, and retires/unretires facilities based on operating status. Built on Akka HTTP with configurable credentials and HFR endpoints.
# UCS-HFR-INTEGRATION-SERVICE
A service used to receive HFR facility updates and refresh location hierarchy into OpenMRS.
## 1. Dev Requirements
1. Java 17
2. IntelliJ or Visual Studio Code
3. Gradle
## 2. Deployment
To build and run the service after performing the above configurations, run the following
```
./gradlew clean shadowJar
java -jar build/libs/ucs-hfr-integration-service- .jar
```
### HFR location endpoints
- `POST /hfr/facility` – accepts a single facility payload from HFR (sample below) and upserts the Region → District → Council → Ward → Facility → Village structure into OpenMRS.
- `POST /hfr/refresh-hierarchy` – pulls the latest facility list and administrative hierarchy from HFR and syncs them into OpenMRS.
Sample facility payload:
```json
{
"Fac_IDNumber": "124899-6",
"Name": "GAKALA",
"Comm_FacName": "GAKALA ",
"Zone": "Lake",
"Region_Code": "TZ.LK.GE",
"Region": "Geita",
"District_Code": "TZ.LK.GE.MW",
"District": "Mbogwe",
"Council_Code": "TZ.LK.GE.MW.3",
"Council": "Mbogwe DC",
"Ward": "Bukandwe",
"Village": "Bukandwe",
"Village_Code": "TZ.LK.GE.MW.3.13.3",
"FacilityTypeGroupCode": "HLCTR",
"FacilityTypeGroup": "Health Center",
"FacilityTypeCode": "HLCTR",
"FacilityType": "Health Center",
"OwnershipGroupCode": "Priv",
"OwnershipGroup": "Private",
"OwnershipCode": "comp",
"Ownership": "Company/Business Name",
"OperatingStatus": "Operating",
"Latitude": "-3.66131",
"Longitude": "32.19689",
"RegistrationStatus": "Registered",
"OpenedDate": "2025-12-15 00:00:00",
"CreatedAt": "2025-07-16 10:31:27",
"UpdatedAt": "2025-09-14 00:30:20",
"Vote": null,
"IsDesignated": 0,
"ClosedDate": "",
"OSchangeOpenedtoClose": "N",
"OSchangeClosedtoOperational": "N",
"PostorUpdate": "P"
}
```
Configuration for OpenMRS/HFR connection lives in `src/main/resources/application.conf`.
## 3. Deployment via Docker
First Install docker in your PC by following this guide. Secondly, clone this repo to your computer by using git clone and the repo's address:
`git …