Introduction

The goal of this project is to increase the scope of the open-source Insurance Management Information System (openIMIS) by developing a standard interface for extending and creating new FHIR APIs (Figure 1) that supports integration of disparate systems via openHIM. The purpose of this document is to provide an overview of design decisions made in the process of integrating OpenIMIS FHIR R4 modules into OpenHIM using opensource tools.

Figure 1: FHIR 4 API design requirements

OpenIMIS Admin Interface

The OpenIMIS Backend is implemented in Django. Django is a high-level Python Web framework that encourages rapid development and clean, pragmatic design. Django is used for:

• ORM Mapping, and help manage the MSSQL database schema via migrations

• Management of user and group Authentication and authorization (out of the box) features.

• The Admin Interface shown in Figure 2 is useful for management of registered OpenIMIS modules.

To expose the API endpoints, a REST interface is built on top of the services/Django models via Django REST Framework. The framework also provides a browsable documentation.

Figure 2: openIMIS Django Admin Interface

OpenHIM Mediators

The Figure below shows the order in which transactions flow through interactions carried out via the OpenHIM. The Python mediators exposes FHIR 4 API endpoints that allows clients or applications to make service requests from a web service through OpenHIM. The Core is responsible for defining and handling all incoming service requests. Service requests are received using a standard protocol HTTPs and translated by the Python Orchestrators into resources accessible by the other components. The Core receives authorized service requests from the mediator forwards it to the upstream server and monitors the transaction to fulfill the request to completion. The received response is stored for logging and audit purposes and can also be used to identify and handle exceptions. The web-based OpenHIM console is used by administrators to identify and solve recurring problems or failures. Note that each mediator contains the necessary logic to normalise, orchestrate and de-normalise that transactions forward or received from the Core.

Open

Figure 3: openHIM reference architecture
The openHIM Core listens on ports 5000 (HTTPS) and 5001 (HTTP). These ports are the interface that clients use to communicate with the OpenHIM core. A client is an external system or App that send request and receive response via OpenHIM core. The Core exposes requested data using API endpoints via HTTPS port 8080. The Admin Console is a web-based interface implemented using AngularJS that makes it easier to manage OpenHIM mediators, client transactions and channels. A Channel defines a path that a client request will take through the OpenHIM. It describes one or more routes for request(s) to be forwarded to client(s) allowed to use the channel.

FHIR 4 OpenHIM Mediators

The integration work package involved developing openHIM mediators that are mapped to OpenHIM core using Python Utils library that was forked from https://github.com/de-laz/openhim-mediator-utils-py. Each of the FHIR4 API endpoints shared by Davis was mapped to OpenHIM mediators developed using Django (Python web framework) as shown in Figure 4. Through the heartbeat functionality in the OpenHIM core, the administrator is able to check for the uptime of an individual mediator.
In this section we provide the implementation details for each workflow documented in the Project's Scope of Work. However, it is important to note that the Workflows for Contribution and Valuated Claims are yet to be implemented due to missing metadata or FHIR4 resources on the HL7-FHIR standard.

Figure 4: OpenHIM Python mediator

Claim Mediators

The Claim workflow shown in Figure 5 was mapped to FHIR4 resource and registered on openHIM claim mediator implemented as a Django app. However, the metadata for Valuated Claim Response need to be discussed for possible extension using FHIR4 Explanation of Benefits (EOB) and/or related FHIR R4 resources.

Open

Figure 5: OpenHIM claim mediator
Django App (Solution) codename: ~/django_openhim_mediators/claim_mediator
Endpoint: http://104.236.37.64:5001/api/api_fhir_r4/Claim
Username: health1
Password: health@123
Supported Methods: GET, POST

Coverage Mediator

The Coverage workflow shown in Figure 6 was mapped to Coverage FHIR4 API and registered on openHIM coverage mediator implemented as a Django app.

Figure 6: OpenHIM coverage mediator
Django App (Solution) codename: ~/django_openhim_mediators/coverage_mediator
Endpoint: http://104.236.37.64:5001/api/api_fhir_r4/Coverage
Username: health1
Password: health@123
Supported Methods: GET, POST

Person and Group FHIR4 Mediator

The Person and Group workflow shown in Figure 7 has been implemented using separate openHIM mediators used to register the two API endpoints that expose Patient/Insuree/Person, and Groups FHIR R4 resources

Figure 7: OpenHIM family and group mediator
Group Mediator
Django App (Solution) codename: ~/django_openhim_mediators/family_mediator
Endpoint: http://104.236.37.64:5001/api/api_fhir_r4/Group
Username: health1
Password: health@123
Supported Methods: GET, POST

Patient Mediator
Django App (Solution) codename: ~/django_openhim_mediators/patient_mediator
Endpoint: http://104.236.37.64:5001/api/api_fhir_r4/Patient
Username: health1
Password: health@123
Supported Methods: GET, POST

Contract Mediator

The Contract workflow shown in Figure 8 was mapped to Contract FHIR4 API and registered on openHIM contract mediator implemented as a Django app.

Figure 8: OpenHIM contract mediator
Django App (Solution) codename: ~/django_openhim_mediators/contract_mediator
Endpoint: http://104.236.37.64:5001/api/api_fhir_r4/Contract
Username: health1
Password: health@123
Supported Methods: GET, POST

Organisation Mediator

The Organisation workflow shown in Figure 9 was mapped to Organisation FHIR4 API endpoint and registered on openHIM organisation mediator implemented as a Django app.

Figure 9: OpenHIM Organisation mediator
Django App (Solution) codename: ~/django_openhim_mediators/organisation_mediator
Endpoint: http://104.236.37.64:5001/api/api_fhir_r4/Organisation
Username: health1
Password: health@123
Supported Methods: GET/POST

Testing openHIM Mediator

To test the mediators, we used insomnia which is an alternative to Postman, Figure 10 shows successful testing of Organisation mediator using POST (push) and GET (pull) operations:

Figure 10: Testing openHIM mediators

To test integration, we used Admin Console that communicates to openHIM core via port 8080. Figures 11 shows the health (heartbeats) of registered python-based mediators used to facilitate FHIR 4 POST (push), GET (pull) and transaction log operations:

Figure11: Console showing registered FHIR4 Python mediators
Figures 12 shows the channels that are used to route request from the client to the upstream openIMIS server. Each channel has URL pattern that maps to openIMIS registered FHIR4 API endpoints:

Fig 12: FHIR 4 Channels corresponding to registered mediators

Integration Challenges and Recommendations

Although the API endpoints shared by Davis have been mapped and registered on openHIM, there are missing endpoints or FHIR4 resources that need to be reviewed or discussed by the development team. For example, we note that contribution resource/endpoint, and valuated claim resource/endpoint/response are not explicitly provided by the FHIR Financial Module. To overcome the challenge of implementing endpoints for these resources/mediators, the following are technical questions that need to be answered:

1. Does claimResponse have sufficient metadata to support valuated claim?

2. At what point in the claim workflow is valuation claim done?

3. Does valuated claim require adjudication and check of eligibility using FHIR eligibility request and response resources?

4. Does FHIR 4 Financial Module provide explicit resource or extensions for Contribution workflow?

Recommendation: Explore the possibility of extending existing FHIR resources or discussing with the development team on possibilities of dropping the deliverable.

Annex

Sample Curl Command

curl --request GET \
--url http://104.236.37.64:5001/api/api_fhir_r4/Organisation \
--header 'Authorization: Basic aGVhbHRoMTpoZWFsdGhAMTIz'
Sample Curl Command (POST Method):
curl --request POST \
--url http://104.236.37.64:5001/api/api_fhir_r4/Organisation \
--header 'Authorization: Basic aGVhbHRoMTpoZWFsdGhAMTIz' \
--header 'Content-Type: application/json' \
--data ' ' #payload goes here
Upon a successful transaction, the transaction details will be recorded on OpenHIM console shown in Figure A1.

Fig A1: FHIR 4 openHIM mediators
Transaction specifics shown in Figure A2 are also stored depending on the settings by the system administrator

Fig A2: FHIR 4 openHIM mediators