Integrating openIMIS with Mifos through openHIM Python Mediators

Throughout the integration, MTCC was guided by Figure 1 that illustrates the overall payment layer architecture as provided by the openIMIS community. The openIMIS system exchanges data through FHIR R4 APIs such as patient (insuree), claim, billing, invoice, organization, etc. Data is sent and/or received from openIMIS to Mifos through openHIM Python orchestration mediators. The openHIM mediators connect to Mifos using FHIR R4 API endpoints that are transformed into Mifos canonical JSON schema for compatibility and interoperability.

Open

 Figure 1: Overall payment layer integration architecture

High-level workflow for integrated openIMIS and Mifos

The following workflow demonstrates how openHIM orchestration mediators facilitate data exchange between openIMIS and Mifos platform as shown in Figure 2. These two systems maintain accounts information which entails tracking balances and charges for registered clients shared between openIMIS and Mifos. The openIMIS FHIR resource for accounts management acts as a central record against which charges, payments, and adjustments are applied. It contains information about which parties are responsible for payment of the account including reference parameters that help in identifying the entity managing the account (organization) and the entity that caused the expense (patient/insuree or organization).

Open

Figure 2: Integrating openIMIS with Mifos through 0penHIM

Payment layer orchestration workflow using Python mediators

A good payment experience should be simple, secure, and fast.  Push (outbound) payments initiated by payers must allow transactions to be processed in local currencies and preferred payment methods. Payouts (outbound) transactions made by payers to payees should also support local currencies and payment channels like e-Wallets. The goal of this project is to extend the openIMIS integrated architecture described above by adding payment modules that support standard payment methods and channels such as shown in Figure 3.

The Figure below shows the order in which transactions flow through interactions carried out via the OpenHIM. The Python mediators expose FHIR 4 API endpoints that allow 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 them 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 normalize, orchestrate and de-normalize those transactions forward or received from the Core.

Figure 3: Payment Layer Orchestration Mediators

The purpose of the Python orchestration mediators is to:

• Provide seamless connections to all required Payment Service Providers (PSPs) and payment methods through FHIR R4 API endpoints.

• Provide intelligent logging and routing capabilities using configurable Django modules that enable quick addition or removal of payment endpoints.

• Leverage on openHIM mediators to track transaction logs, statuses, and payment costs.

For seamless integration between openIMIS and Mifos through openHIM, we have developed openHIM mediators that implement canonical conversion depicted in Figure 4.

Fig 4: openIMIS Payment layer orchestration architecture

Canonical Transformation of FHIR R4 resources into Mifos JSON Schema

Many integration scenarios require translating messages from one data model to another before performing processes such as data validation, data integration, or data interoperability. The JavaScript Notation (JSON) stands out as a standard for representing and exchanging data between disparate systems and/or data formats. However, the challenge is to minimize dependencies when integrating applications that use different JSON schemas and data formats.

A Canonical Data Model provides an additional level of indirection between the application's individual data formats. If a new application is added to the integration solution only transformation between the Canonical Data Model has to be created, independent from the number of applications that already participate. Canonicalization is the process of converting data that involves more than one representation such as FHIR+JSON into a standard approved JSON format known as Canonical Data Model. To integrate OpenIMIS Payment Layer with Mifos through OpenHIM, we developed a Canonical Data Model that ensures conversion of FHIR R4 resources to Mifos and vice versa conforms to semantic integration rules. Figure 5 illustrates the graphical model of the OpenIMIS-to-Mifos Canonical transformation that converts openIMIS Patient Resource into a standard Mifos Client JSON Object.

 Figure 5: Model for Canonical transformation of FHIR R4 to Mifos JSON Schema

Figure 6 illustrates the physical implementation of the canonical model by renaming or removing property keys, replacing namespace references, and eliminating redundant values. The function implemented in Python also removes FHIR resource type declarations, extensions, absolute URLs, and character encodings that are not supported by the Mifos JSON Schemas. To test these transformations, we used openHIM orchestration mediators that monitor and generate transaction logs from request and response payloads consumed from OpenIMIS and Mifos (See annex 2).

Figure 6: Canonical transformation of openIMIS patient to Mifos client

To construct an openIMIS FHIR R4 or Mifos object with the required properties, we implemented Python methods (functions) in Django that performs the following:

• Mapping translation workflows between different hierarchical levels. This is achieved by flattening and recursively transforming FHIR R4 nested lists (arrays and dictionaries) into Mifos JSON Schemas using a Python function provided in Annex 1

• Normalizations from different JSON and string formats to an internal canonical model supported by openIMIS or Mifos data models

• Content Filtering to remove unnecessary, redundant, or sensitive information coming from Mifos or openIMIS payloads

• Payload orchestration to enrich content with different input messages, envelop wrappers, and metadata extracted or exchanged by integrated systems.

• Sending GET and POST payloads to the upstream server (Mifos or openIMIS) using Python-based APScheduler library that implements trigger functions. This complements the roles played by openHIM polling channels and RESTHook expected to manage subscription-based resource sharing.

CONCLUSION AND RECOMMENDATIONS

The openIMIS system exchanges data through FHIR R4 APIs such as patient, claim, billing, invoice, and organization using FHIR+JSON format. However, data received by Mifos through openHIM must conform to native JSON format. Therefore, orchestration mediators should handle the complexity of transforming disparate schemas and formats without the loss of input or output values shared between the two systems. The canonical transformation model published in this documentation provides the algorithmic and business logic for transforming a complex FHIR R4 resource object containing nested object hierarchies into standard JSON schema consumed by Mifos.

The algorithmic model implemented in Python utilizes recursive tree traversal that may require rigorous testing in a real-world scenario to determine its performance in terms of time and space complexity!  Such tests of the algorithm were limited within the current project due to constraints of time and limited resources. There is also a need for developers to maintain updated documentation and version control of the main branch of all the subsystems within the integration ecosystem. This way, the wider development community will contribute to better implementation, scaleup, and maintenance of the integrated ecosystem comprising of openIMIS, Mifos, openHIM, and Mojaloop.

ANNEXES

ANNEX 1

Figure A1: Mediators Functions for canonical transformation of Patient FHIR Resource

ANNEX 2

Figure A2: Payload for openIMIS FHIR R4 Patient resource