Instant OpenHIE

Microservice and devtools have been replaced by Lightning

Please note that OpenFn/microservice and OpenFn/devtools are being deprecated and replaced by OpenFn/lightning. Lightning may be used within Instant OpenHIE (instead of microservice) as an OpenHIE-compliant workflow engine that can interface with the OpenHIE Interoperability Layer (learn more).

Overview

In partnership with Digital Square and FCDO COVIDaction, OpenFn has been investing in its open source integration toolkit to provide robust integration solutions that can connect any digital health system and be rapidly implemented on any server, in any country, by any organization.

OpenFn/microservice is a fully Instant OpenHIE compliant component which can be used to drive workflow, achieve compliance with standards, and integrate components of the OpenHIE stack.

We seek to enhance the value of the Instant OpenHIE project by developing a package that will include OpenFn as an integration pathway for connecting with the OpenHIE architecture.

This package aims to enhance the value of Instant OpenHIE by providing another option for robust information processing, integration, and business process (workflow) automation. When deploying Instant OpenHIE, implementers now have the option to include OpenFn as a component.

OpenFn may also be used as a workflow engine to automate complex business logic alongside OpenHIM and the OpenHIE stack. Individual jobs in OpenFn, sometimes many in a single microservice deployment, may be used as “mediators” (see OpenHIE library of existing mediators) to quickly transform and map data to the OpenHIE architecture.

To demonstrate a real-world use case for how OpenFn might be implemented in the OpenHIE architecture, we met with several community members to identify key use cases for a reference prototype implementation.

Visit the demo repo here.

Use Cases for the Prototype Implementation

We’ve seen that the most common integration use case is that health service delivery providers, especially large community health worker (“CHW”) interventions, need to integrate their data and programming into national eHealth architectures.

User stories

1. As a community health implementer, I want to integrate my CommCare case management application used by CHWs with the national patient registry, so that I can develop a shared health record and automate reporting pipelines.
2. As a health services provider, I want to integrate my existing application with the national HIS, but I want to apply the FHIR standard to my data collected before sharing to adhere to compliance and reporting requirements.

• We therefore decided to build an integration solution that demonstrates how existing CHW applications can be integrated with the national health infrastructure and leverage a simple job on OpenFn as a mediator to apply the FHIR data standard and other data manipulation needed to integrate with HAPI FHIR.

Implementation Design

In sum, the prototype sends patient case registration data from mobile data collection apps (CommCare, KoboToolbox) to OpenFn/microservice. OpenFn then transforms the data and ensures that it adheres to the FHIR patient and encounter data standards, before sending it onwards to a FHIR channel in the OpenHIM. OpenHIM is used as a _“channel”_ here for the OpenHIE architecture to validate requests and forward them onto other systems in the national eHealth architecture. In this case, we forward the case data onwards to register the patients in a HAPI FHIR server.

This implementation design was determined to be the highest value/most in-demand because it leverages the core functionality of OpenHIM (providing a reverse proxy and generating an audit trail) without requiring integrators to build a new mediator—a process that is more complex than configuring a job within an OpenFn project.

This prototype includes the following components:

An Instant OpenHIE instance can be spun up which contains HAPI FHIR, OpenHIM, and a single OpenFn/microservice deployment (a project.yaml file, exported from OpenFn/platform) with 2 different jobs. When data is forwarded to OpenFn/microservice from two distinct form submissions on CommCare and Kobo, it is processed and creates FHIR patient resources via OpenHIM and HAPI FHIR. We’ve opted for a single OpenFn/microservice “project” with two slightly different jobs and triggers to highlight the versatility of OpenFn projects.

Explore the Implementation

Currently, there are two different ways to explore this demo. The first (the more traditional “Instant” way) is by cloning the OpenFn/instant-demo repo. Once inside, users type “yarn setup” to get everything up and running. Running “yarn test” will then demonstrate the Kobo/CommCare to OpenFn to OpenHIM to FHIR flows.

They can explore the various jobs, sample payloads, endpoints, and post data to the various endpoints using either the data forwarding settings in CommCare and Kobo or via CURL (or their HTTP request agent of choice.)

Once running, users can see how standard CommCare and Kobo submissions are transformed by the OpenFn/microservice to adhere to the FHIR specifications for patients and encounters, and then that those subsequent resources are created on the HAPI FHIR server, via a channel on the OpenHIM.

The second (slightly less conventional way) to explore the demo, is via OpenFn.org. Since OpenFn projects can be run in microservice or on the hosted platform, we’ve provided a project instance at OpenFn.org that allows users to explore the configuration required to incorporate OpenFn in an Instant OpenHIE project. There are three jobs which can be accessed with a demo user with username: demo@openfn.org and password:guest123.

The three jobs will show:

• How a CommCare submission is transformed and sent to HAPI FHIR;
• How a Kobo submission is transformed and sent to HAPI FHIR;
• And what the final resources that would be sent to HAPI FHIR look like.

It’s our hope that this will provide a valuable entry-point for Instant OpenHIE configuration with OpenFn/microservices.

About the Implementation Setup

Processes

• We met with OpenHIE community members to understand use cases, and with Jembi Health Systems to learn about Instant OpenHIE packages, specifications, and compliance requirements.

• Identified sample data sources (real CommCare and Kobo case registration forms - see here) that we could use to send data to the national eHealth architecture. Here is a sample submission payload from CommCare Here is a sample submission payload from Kobo

• Reviewed FHIR-HL7 documentation to determine data standard requirements for patient data and encounter data. See FHIR patient spec and FHIR encounter spec.

• Evaluated OpenFn vs. OpenHIM capabilities to determine how to use. Determined that using an OpenHIM channel will leverage the core audit trail functionality from OpenHIM, but not require us to build a new mediator.

Project Configuration Steps

There are two ways to set up a project.yaml to run as a microservice. The first is to use the OpenFn.org platform, and the second way is to use OpenFn/devtools.

These two methods are detailed below:

1. Configure a project using the OpenFn.org platform

   • This option allows organisations to leverage OpenFn.org’s built-in features for easy project setup, job writing and source code management.

   • The project.yaml file generated from this project setup will then be used as the base structure for the OpenFn Microservice.

   • The steps to setup the OpenFn Microservice project using the OpenFn.org platform are as below:

     A. Add credentials to the project which will be used to connect the OpenFn Microservice to OpenHIM.

     • This is also an opportunity to add credentials which OpenFn Microservice may use to connect to source systems (such as CommCare or KoBotoolbox) .

     B. Add triggers to the project which will be used by the OpenFn Microservice to match payloads from source systems to OpenFn Microservice Jobs.

     • Note that the Microservice is configured to run a job based on the shape of the incoming payload.

     • For example, a trigger may be configured to match payloads, from CommCare, which contain the {"@name": "Register New Patient"} message in their message body.

     • A given job will then match against this message, and will be invoked by the OpenFn Microservice to (a) create a payload in the FHIR standard containing an Encounter Resource and (b) send the FHIR Standard Payload to OpenHIM with instructions to load it to HAPI FHIR.

     C. Export the project.yaml file using the Export Wizard of the OpenFn.org

     • The generated YAML file will then be used by the OpenFn Microservice to execute the jobs for the matching payloads.

2. Configure a project using the OpenFn/devtools

   • This option allows organisations to configure the project and host job expression source files, for OpenFn Microservice projects, without using the OpenFn platform.

   • With this option, it is recommended that organisations use source versioning tools and platforms such as git and github to manage the project and job expression source code/files.

   • To configure the OpenFn Microservice project using OpenFn/devtools, create a local folder or github repository to host your project configuration files. Inside this folder, one would then perform the following actions:

     • Create a credential.json file

     • Add credentials as shown in the sample credential here

     • Create the job expressions. In this case, one would create the CommCare-to-OpenHIM and Kobo-to-OpenHIM expressions as shown in the demo expressions here

     • Run the OpenFn CLI to configure the rest of the project. The CLI will assemble the project.yaml file from the different artifacts as provided. See detailed steps in the documentation site here.

     • The last step of the CLI prompts will allow one to export the Project YAML file, which will then be used by the OpenFn Microservice to execute the jobs for matching payloads.

Job writing notes

OpenFn provides two ways of writing jobs:

• Using the OpenFn.org’s Job Studio as detailed in the documentation site here
  • With this option, if editing an existing Job Expression, one would be expected to use OpenFn.org Project Export service to re-generate the Project YAML file for the OpenFn Microservice.
• Using OpenFn/devtools.
  • This option also allows organisations to write job expressions without using the OpenFn’s hosted service. See detailed documentation here
  • With this option, if editing an existing Job Expression, one would be expected to run the OpenFn CLI, to re-generate the Project YAML file for the OpenFn Microservice.

System Deployment Steps

• OpenFn provides an automated deployment script that allows system admins to setup and run the OpenFn Microservice.
• For example, to run the Instant-demo Microservice, the following steps are recommended:
  • Clone the OpenFn/instant-demo repo
  • Overwrite the sample “project.yaml” file with your newly generated project.yaml file, or use the existing YAML file to deploy the demo project. Run the setup command as described in the documentation here
  • Verify the system is working by curling data (or submitting forms on CommCare/Kobo) matching their triggers to the microservice endpoint (localhost:4001/inbox) and checking to see that resources are created in HAPI FHIR.
  • Note how the test.js file handles this verification with the sample project.yaml