Botswana HIE

Owned by Taib
Last updated: Oct 30, 2024 by Beth Dunbar
7 min read

GitHub

Components

Install Instructions

Install docker and docker-compose commands:

Domain vs. Port-based Setup

Decide whether you're running a domain-based or port-based setup. Based on this, either use the docker-compose.yml file for domain-based, or the docker-compose.local.yml file for port-based.

This decision determines how services will be reached, and what environment needs to be used for testing. In each case, the traffic is routed through the nginx container, which distributes the traffic correctly based on domains or ports. See the nginx configuration in the corresponding docker-compose.yml file, and the configurations in ./configs/nginx.

We assume a port-based setup for these instructions.

Check out repository:

git clone https://github.com/B-TECHBW/hie-botswana.git

Start up core containers:

cd hie-botswana docker-compose -f docker-compose.local.yml up -d openhim-core openhim-console mongo-db opencr-fhir shr-fhir opencr-es kafka zookeeper nginx

OpenHIM Password Setup:

Open the OpenHIM console in the browser and use default login and password: root@openmrs.org/openhim-password. Change the password when prompted to one that your mediators will use.

Start up mediators:

Ensure the chosen password is set correctly in the configuration files for these mediators in the mediator:api:password setting:

Then, start up the mediators:

docker-compose -f docker-compose.local.yml up -d shr opencr fhir-converter

You can check the logs of the mediators by running:

docker-compose -f docker-compose.local.yml logs shr opencr fhir-converter

HIE Testing Guide

These instructions will assume a port-based approach when giving examples, so you can swap in the corresponding domain-based urls from the nginx.conf files.

Step 1: Verify access to OpenHIM

Make sure console is up and running, and pointed to the correct, external (non-docker) url for the openhim-core api (port 8080):

docker logs -n 100 openhim-console

Make sure openhim-core is running correctly:

docker logs -n 100 openhim-core

Open openhim console url in browser window: https://localhost

Log in using default password and set a new admin password if not done already, using the following defaults: root@openmrs.org/openhim-password

Make sure whatever password you choose is updated in the opencr, shr, and fhir-converter config files.

You should now be logged into the OpenHIM Dashboard.

Step 2: Activate and Verify the Mediators

Go to Mediators tab in OpenHIM console.

Verify that the following three mediators are registered and have active (green) heartbeats: - OpenCR - SHR - FHIR-HL7 Converter

Add the channels associated with each mediator with the green + button.

Go to the Clients and Roles tab and create the following roles and channel assignments:

  • shr-client (all SHR mediator channels)

  • opencr-client (all OpenCR mediator channels)

  • converter-client (all Fhir Converter mediator channels)

  • mfl-client (placeholder)

  • omang-client (placeholder)

  • bd-client (placeholder)

In the clients section, create the following clients and assign roles:

  • pims-test(shr-client, opencr-client, mfl-client)

  • ipms-test(shr-client)

  • shr(opencr-client, converter-client, mfl-client, omang-client, bd-client)

  • opencr(converter-client, omang-client, bd-client)

For each client, add Basic Auth authentication in the Authentication tab. The client name will be the username for BasicAuth, and will need to be set correctly in configurations for the communication workflows to work. For production, certificate-based authentication will be used.

To enable testing, the following temporary client should also be created and given access to all of the listed roles: postman/postman. If a password other than this default is required, the corresponding settings need to be updated in each .json file in .postman/collections for the tests to run correctly.

Run Postman Tests

Verify that the .postman/postman_env.moh.json environment file has the correct urls for the setup to be tested.

Run the tests:

./.postman/run-tests-offline.sh

Run MLLP Tests

For this test, the test will respond with success if it passes, and it will log a couple transactions in the OpenHIM console.

Run the tests:

sudo docker-compose -f docker-compose.local.yml up mllp_tests

Offline Install

  • Pull and save images on internet-connected machine

git clone https://github.com/B-TECHBW/hie-botswana.git cd hie-botswana ./dist/build_package.sh

  • Transfer the dist folder with the .tar files to server

  • Unpack .tar files to docker images

./load_package.sh

Boot up Docker containers

See Docker Install Instructions section

Certificate Management

For AWS setups, we use Letsencrypt to provide SSL certificates for the domain. See https://nandovieira.com/using-lets-encrypt-in-development-with-nginx-and-aws-route53 for more guidance.

Certificates are grabbed/managed by the certbot service in the docker-compose.yaml file. This service requires the following variables: AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. See Welcome to certbot-dns-route53’s documentation! https://certbot-dns-route53.readthedocs.io/en/stable/ for information on how to obtain these values in AWS.

Certificate generation and renewal will eventually be automated, but currently can be run with the following command: sudo -E docker-compose up certbot

The certificates are loaded into the certs volume, which can be mounted in any other docker container, and is primarily used by Nginx.

Dev Guide: Botsawana Laborabory Workflows

Introduction

This guide will go over development, configuration, and debugging the laboratory workflow for Botswana. This workflow includes functionality in the SHR and Fhir Converter projects, linked below:

The functionality includes Kafka-managed workflows in the SHR project, and FHIR --> HL7 and HL7 --> FHIR mappings in the Fhir Converter project.

Prerequesites

Before getting started, make sure you complete the following prerequisites:

1. Connect to the Botswana VPN

See the relevant emails and slack messages for instructions.

2. Add the following ssh config to your ~/.ssh/config file:
3. Connect to the HIE server using remote VS Code

See slack for the password.

4. Set up the relevant VS Code projects by opening the following folders:

The first two are used for development of the SHR and the FHIR Converter, respectively. The third is the main project for running the HIE. We run all the other containers EXCEPT FOR the shr and fhir-converter containers from that project.

5. Add remote debugging configurations to the SHR and FHIR Converter projects

Add the following configurations to the .vscode/launch.json files in the SHR and FHIR Converter projects:

You can open the file by clicking the debug icon on the left side of the VS Code window, then clicking the gear icon next to the "Run and Debug" dropdown, then clicking "Open launch.json".

5.1. SHR
5.2 FHIR Converter
6. Forward the following ports in VS Code for the SHR and FHIR Converter projects:

  • SHR: 9229

  • FHIR Converter: 9230

Useful Docker Commands

1. Show logs of shr, shr-fhir, and fhir-converter containers
2. Rebuild and run SHR or FHIR Converter containers
3. Rebuild and Reset the FHIR Converter templates after making changes

The templates are stored in a volume, so you need to remove the volume and rebuild the container to update any changes made to the templates.

Overview of project structure and code locations

1. SHR

The SHR project contains two main that has all of the Botswana-specific workflows. One focuses on FHIR-based workflows, and the other manages the incoming HL7 messages.

The FHIR-based workflows for Botswana are located in src/workflows/labWorkflowsBw.ts: https://github.com/I-TECH-UW/shared-health-record/blob/pmanko-lab-workflow-updates/src/workflows/labWorkflowsBw.ts .

The HL7-based workflows are located in src/workflows/hl7WorkflowsBw.ts: https://github.com/I-TECH-UW/shared-health-record/blob/pmanko-lab-workflow-updates/src/workflows/hl7WorkflowsBw.ts

The workflows are organized using Kafka topics and picked up by Kafka workers.

2. FHIR Converter

The FHIR Converter project contains the mappings from FHIR to HL7 and HL7 to FHIR. The mappings are located in the data/templates directory: https://github.com/I-TECH-UW/openhim-mediator-fhir-converter/tree/pmanko-server-update/data/templates

The relevant templates are ADT_A04_TO_IPMS.hbs and ORM_O01_TO_IPMS.hbs in the fhir subdirectory and ADT_A04_FROM_IPMS.hbs and ORU_R01_FROM_IPMS.hbs in the hl7 subdirectory.

2.1. HL7 to FHIR

For the HL7-->FHIR templates in the data/templates/hl7 directory, there are nested handlebar template files that provide variable replacement for references to the HL7 message field names.

2.2. FHIR to HL7

For the FHIR-->HL7 templates in the data/templates/fhir directory, the variable replacement is done using custom mappings defined in the parseAdt() and parseOrm() functions in the /src/lib/fhir/fhir.js file: https://github.com/I-TECH-UW/openhim-mediator-fhir-converter/blob/e1f8085258b95735559c69d5f36eaf5ff0fd272b/src/lib/fhir/fhir.js#L107 . The correct variables need to be added to the res object, and are then available as variables in the handlebar templates.

Turning on Remote Debugging for the projects:

Make sure that the docker-compose entries in the debug.docker-compose.yml files for the SHR and FHIR Converter projects have debugging turned on for their respective projects.

The Fhir Converter project should have the following entrypoint entry:

The SHR project should have the following entrypoint entry:

Make sure that you have the Remote Debugging setup as outlined in the Prerequisites section of this guide.

Make sure that you have the relevant ports forwarded in VS Code for the SHR and FHIR Converter projects.

Finally, make sure that you run yarn build on the project you want to debug, and also that you ran docker-compose -f debug.docker-compose.yml up --build -d after making any changes to the code to see them reflected in the running container.

Postman Overview

The Postman collection for the Botswana HIE Lab Workflows is located here: https://www.postman.com/itechuw/workspace/botswana-hie/collection/1525496-8be9c19c-9e7b-4316-adea-3604884af5d7?action=share&creator=1525496

For IPMS testing, we focus on the following folder: https://www.postman.com/itechuw/workspace/botswana-hie/folder/1525496-0c135557-d6a8-4928-a649-2546a18d075f?ctx=documentation

We also use the hie-pilot.gov.bw environment.

The Add Draft Order Bundle request sends a draft order that does result in concept and location mappings, but does not send an HL7 message to IPMS. It also generates new patient data as outlined in the Pre-request Script tab.

The Add Requested Order Bundle request sends a requested order that does concept and location mappings, and also sends an HL7 message to IPMS. It uses the data generated by the Add Draft Order Bundle request, and can be re-run multiple times with the same patient information.

OpenHIE Testing

For quickly testing changes to the Fhir Converter templates, you can re-run the converter request from OpenHIE, which can be accessed here:

https://hie-pilot.gov.bw/

This page loads slowly as it tries to pull external resources that are not available on the network.