This document acts as a software requirements specification for an interaction between OpenLMIS version 3 and a facility registry.

Background

OpenLMIS contains a conceptual model of locations, geographic levels, geographic zones, supply lines and supervising nodes. Much of this information is domain specific, but has overlap at the lowest level, where health services are being provided. A facility registry is historically used to represent a list of all health facilities within a country where care is delivered. This facility list is often curated by a ministry of health at national level and changes regularly. These domains overlap with a common definition of locations. For example, a district hospital will likely be represented in both domains as both a point of service, a location that can receive stock and a location that can supply other locations with stock. We often need to generate reports across both domains where there is this overlap.

Goal

The goal of this integration is to support a common definition of locations in both the health and supply chain domains so we can more easily exchange information using open standards. This will add value to health systems who aim to support cross domain reporting, scheduling of resources and demand generation of commodities. This integration is a core metadata element that unlocks multiple workflows toward interoperability in any given context.

Scope

The scope of this software requirements specification is as follows:

We will focus on integrating with a facility registry using the mCSD standard which currently requires adherence to the FHIR STU2 protocols
We will focus on sharing location information only, not the other information related to organizations, providers and services delivered at each location. These other items have minimal value for OpenLMIS.
We will support the core workflow where OpenLMIS is a producer of location information that is consumed by the Interlinked Registry (ILR)

Out of Scope

The following items are out of scope for this minimum viable product:

There is another workflow where a facility registry registers all locations and OpenLMIS acts as a consumer of that information. It is a lower priority due to lower value for the OpenLMIS community. That workflow is labeled as workflow 1 on this page.
Entity matching is out of scope of this project. Entity matching is the process in the Health Information Exchange where multiple facility hierarchies are evaluated and matched. This process, for example will match a facility from OpenLMIS to it's DHIS2 counterpart so items can be appropriately routed. The Global Open Facility Registry project has a UI that can support this matching and OpenHIE has an entity matching service as part of the interoperability layer services that can support it without a UI.

Assumptions

We make the following assumptions with this integration:

We will use OpenHIM as the interoperability layer (IOL), specifically the OpenHIM Docker image
We will use HEARTH as the health facility registry (interlinked registry, a.k.a. IRL), specifically the Docker Hub HEARTH image
All interactions with the facility registry will use FHIR standards as outlined in the mCSD specification (ITI-90)

Evaluation

The team evaluated the maturity of the OpenLMIS location endpoint and identified that it would require significant rework to become compliant with the FHIR standards as outlined in the mCSD specification. This rework is untenable given the environment and we identified that Jembi's Hearth platform could serve as the FHIR interface for OpenLMIS. Hearth is a FHIR server that already has many endpoints to achieve the functionality that's needed for this and many other FHIR based integrations. We will focus on running Hearth as a microservice, exchanging information from the OpenLMIS APIs to Hearth on a regular schedule using Nifi.

Architecture

This integration requires a number of components. This section defines the architecture and roles of each system.

OpenLMIS - OpenLMIS version 3 is the source of truth for supply chain related location information. It is comprised of multiple microservices that are available by a RESTful API. Consul is a service that's responsible for registering and managing routing between microservices within the OpenLMIS architecture. The Referencedata Microservice is source of geographic information in the OpenLMIS v3 architecture exposed through the API.

Hearth Microservice - We will run Hearth as a microservice within the OpenLMIS v3 architecture, packaged, registered with consul and made available through docker-compose files. It will be responsible for storing information in FHIR format and exchanging information in that format with other services.

Nifi - Apache Nifi is the OpenLMIS v3 integration engine. It will be responsible for querying the Referencedata microservice, performing business logic, converting to a FHIR resource and posting information to Hearth.

OpenHIM (Interoperability Layer) - OpenHIM is part of the health information exchange's interoperability layer, which acts as an access control, auditing and routing layer for the HIE. OpenHIM will trigger regular updates for the HIE.

Hearth Interlinked Registry (ILR) - Hearth is running as the interlinked registry and is contains geographic information for multiple sources.

Facility Registry - A facility registry is expected to be part of the health information exchange. In this use case the ILR manages all interactions with the facility registry and we do not need to interact with it.

Workflows

Workflow 1 is an internal workflow that updates the Hearth Microservice on a regular schedule with new geographic information.

WebSequenceDiagram Code

title Workflow 1: OpenLMIS Internal - Update Hearth Microservice

participant Referencedata Microservice
participant Nifi
participant OLMIS Hearth Microservice

Nifi->Nifi: Cron Trigger
Nifi->+Referencedata Microservice: Query api/locations
Referencedata Microservice->-Nifi: Return results
Nifi->Nifi: Identify updates
loop For each update, post the location
Nifi->+OLMIS Hearth Microservice: POST the location
OLMIS Hearth Microservice->-Nifi: Return Success
end

Workflow 2 is the workflow where OpenLMIS acts as a source of geographic information for the Interlinked Registry

WebSequenceDiagram Code

title Workflow 2: OLMIS is a producer of location information

HIM->HIM: Cron Trigger
HIM->OLMIS Hearth Microservice: GET updates
OLMIS Hearth Microservice->HIM: Response
HIM->ILR: Put/POST Facilities

Overview of Development Required

This section provides a high level overview of the software development components that will be required.

OpenLMIS

Add Hearth as a microservice registered with Consul (Already in progress)

Nifi

Develop the internal flow as defined in Workflow 1
- Make sure to keep a cache of the last known state from the referencedata microservice
Develop a processor to convert the JSON response to the FHIR standard
(Optional) Write a process for standing up Nifi independently for this integration OR if it's already running, loading in the specific template from the registry.
Note: These templates should be made available on the Nifi Registry and downloadable for any existing implementation of Nifi.

Hearth - No development work needed

OpenHIM

Develop a mediator that has a cron trigger to trigger the updates
Implement ITI-90 within a mediator

Sandbox Environment - Already in development

Develop a sandbox environment that stands up the HIE for integration testing