Please note that OpenFn/microservice and OpenFn/devtools are being deprecated and replaced by OpenFn/lightning, When Lighting is released, it 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).
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.
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.
- 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.
- 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.
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: firstname.lastname@example.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.
About the Implementation Setup
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
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
These two methods are detailed below:
Configure a project using the OpenFn.org platform
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) .
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.
Configure a project using the OpenFn/devtools
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
Job writing notes
OpenFn provides two ways of writing jobs:
- Using the OpenFn.org’s Job Studio as detailed in the documentation site here
- 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